API docs by Redocly

App Services Admin API (3.2)

Download OpenAPI specification:Download

License: Business Source License 1.1 (BSL)
⬆️ Manage App Services with the App Services API

Introduction

App Services manages access and synchronization between Couchbase Lite and Couchbase Capella. The App Services Admin REST API is used to administer user accounts and roles, and to run administrative tasks in superuser mode.

Session

Get information about the current user

This will get the information about the current user.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

Responses

Response samples

Content type
application/json
{
  • "authentication_handlers": [
    ],
  • "ok": true,
  • "userCtx": {
    }
}

Create a new user session

Generates a login session for a user and returns the session ID and cookie name for that session. If no TTL is provided, then the default of 24 hours will be used.

A session cannot be generated for an non-existent user or the GUEST user.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

Request Body schema: application/json

The body can depend on if using the Public or Admin APIs.

name
string

User name to generate the session for.

ttl
integer

Time until the session expires. Uses default value of 24 hours if left blank.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "ttl": 0
}

Response samples

Content type
application/json
{
  • "session_id": "c5af80a039db4ed9d2b6865576b6999935282689",
  • "expires": "2022-01-21T15:24:44Z",
  • "cookie_name": "SyncGatewaySession"
}

/{db}/_session

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Get session information

Retrieve session information such as the user the session belongs too and what channels that user can access.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

sessionid
required
string

The ID of the session to target.

Responses

Response samples

Content type
application/json
{
  • "authentication_handlers": [
    ],
  • "ok": true,
  • "userCtx": {
    }
}

Remove session

Invalidates the session provided so that anyone using it is logged out and is prevented from future use.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

sessionid
required
string

The ID of the session to target.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Remove all of a users sessions

Invalidates all the sessions that a user has.

Will still return a 200 status code if the user has no sessions.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

name
required
string

The name of the user.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Remove session with user validation

Invalidates the session only if it belongs to the user.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

name
required
string

The name of the user.

sessionid
required
string

The ID of the session to target.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Database Security

Get a user

Retrieve a single users information.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

name
required
string

The name of the user.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "password": "string",
  • "admin_channels": [
    ],
  • "all_channels": [
    ],
  • "collection_access": {
    },
  • "email": "string",
  • "disabled": true,
  • "admin_roles": [
    ],
  • "roles": [
    ],
  • "jwt_roles": [
    ],
  • "jwt_channels": [
    ],
  • "jwt_issuer": "string",
  • "jwt_last_updated": "2019-08-24T14:15:22Z"
}

Upsert a user

If the user does not exist, create a new user otherwise update the existing user.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

name
required
string

The name of the user.

Request Body schema: application/json

Properties associated with a user

name
string

The name of the user.

User names can only have alphanumeric ASCII characters and underscores.

password
string

The password of the user.

Mandatory. unless allow_empty_password is true in the database configs.

admin_channels
Array of strings

A list of channels to explicitly grant to the user for the default collection.

object

A set of access grants by scope and collection.

email
string

The email address of the user.

disabled
boolean

If true, the user will not be able to login to the account as it is disabled.

admin_roles
Array of strings

A list of roles to explicitly grant to the user.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "password": "string",
  • "admin_channels": [
    ],
  • "collection_access": {
    },
  • "email": "string",
  • "disabled": true,
  • "admin_roles": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Delete a user

Delete a user from the database.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

name
required
string

The name of the user.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Check if user exists

Check if the user exists by checking the status code.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

name
required
string

The name of the user.

Responses

Get all names of the roles

Retrieves all the roles that are in the database.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

query Parameters
deleted
boolean
Default: false
Enum: true false

Indicates that roles marked as deleted should be included in the result.

Responses

Response samples

Content type
application/json
[
  • "Administrator",
  • "Moderator"
]

Create a new role

Create a new role using the request body to specify the properties on the role.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

Request Body schema: application/json

Properties associated with a role

name
string

The name of the role.

Role names can only have alphanumeric ASCII characters and underscores.

admin_channels
Array of strings

The channels that users in the role are able to access for the default collection.

object

A set of access grants by scope and collection.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "admin_channels": [
    ],
  • "collection_access": {
    }
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

/{db}/_role/

Required Sync Gateway RBAC roles:

  • Sync Gateway Architect
  • Sync Gateway Application
  • Sync Gateway Application Read Only
path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Get a role

Retrieve a single roles properties.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

name
required
string

The name of the role.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "admin_channels": [
    ],
  • "all_channels": [
    ],
  • "collection_access": {
    }
}

Upsert a role

If the role does not exist, create a new role otherwise update the existing role.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

name
required
string

The name of the role.

Request Body schema: application/json

Properties associated with a role

name
string

The name of the role.

Role names can only have alphanumeric ASCII characters and underscores.

admin_channels
Array of strings

The channels that users in the role are able to access for the default collection.

object

A set of access grants by scope and collection.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "admin_channels": [
    ],
  • "collection_access": {
    }
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Delete a role

Delete a role from the database.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

name
required
string

The name of the role.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}

Check if role exists

Check if the role exists by checking the status code.

path Parameters
db
required
string
Example: db1

The name of the database to run the operation against.

name
required
string

The name of the role.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "reason": "no such database \"invalid-db\""
}