openapi: 3.0.3
info:
  title: App Services Admin API
  description: >-
    # 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.
  version: '4.0'
  license:
    name: Business Source License 1.1 (BSL)
    url: 'https://github.com/couchbase/sync_gateway/blob/master/LICENSE'
servers:
  - url: 'https://{hostname}:4985'
    description: Admin API
    variables:
      hostname:
        description: The hostname to use
        default: localhost
externalDocs:
  description: ⬆️ Manage App Services with the App Services API
  url: rest-api-introduction.html
paths:
  '/{db}/_session':
    parameters:
      - name: db
        in: path
        required: true
        schema:
          type: string
        example: db1
        description: The name of the database to run the operation against.
    get:
      summary: Get information about the current user
      operationId: get_db-_session
      tags:
        - Session
      description: This will get the information about the current user.
      responses:
        '200':
          description: Properties associated with a user session
          content:
            application/json:
              schema:
                type: object
                properties:
                  authentication_handlers:
                    description: >-
                      The ways authentication can be established to authenticate
                      as a user. Used for CouchDB compatibility. Always contains
                      "default" and "cookie".
                    type: array
                    enum:
                      - - default
                        - cookie
                    default:
                      - default
                      - cookie
                  ok:
                    description: Used for CouchDB compatibility. Always true.
                    type: boolean
                    enum:
                      - true
                  userCtx:
                    type: object
                    properties:
                      channels:
                        description: >-
                          A map of the channels in the default collection that
                          the user is in along with the sequence number the user
                          was granted access. This does not include inherited
                          channels through roles.
                        type: object
                        additionalProperties:
                          x-additionalPropertiesName: channelName
                          type: number
                          minimum: 1
                          description: The sequence number the user was granted access.
                          title: sequence number
                        example:
                          '!': 1
                          channelA: 2
                      name:
                        description: The name of the user.
                        type: string
                        minLength: 1
                    required:
                      - channels
                      - name
                required:
                  - authentication_handlers
                  - ok
                  - userCtx
                title: User Session Information
        '404':
          description: Resource could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
    post:
      summary: Create a new user session
      description: >
        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.
      requestBody:
        description: The body can depend on if using the Public or Admin APIs.
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: User name to generate the session for.
                  type: string
                ttl:
                  description: >-
                    Time until the session expires. Uses default value of 24
                    hours if left blank. This value must be greater or equal to
                    1.
                  type: integer
      operationId: post_db-_session
      tags:
        - Session
      responses:
        '200':
          description: >-
            Session created successfully. Returned body is dependant on if using
            Public or Admin APIs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id:
                    description: >-
                      The ID of the session. This is the value that would be put
                      in to the cookie to keep the user authenticated.
                    type: string
                  expires:
                    description: The date and time the cookie expires.
                    type: string
                  cookie_name:
                    description: >-
                      The name of the cookie that would be used to store the
                      users session.
                    type: string
              examples:
                Example:
                  value:
                    session_id: c5af80a039db4ed9d2b6865576b6999935282689
                    expires: '2022-01-21T15:24:44Z'
                    cookie_name: SyncGatewaySession
        '401':
          description: 'User does not have access to resource, or resource does not exist'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
        '404':
          description: Return if database does not exist
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
  '/{db}/_session/{sessionid}':
    parameters:
      - name: db
        in: path
        required: true
        schema:
          type: string
        example: db1
        description: The name of the database to run the operation against.
      - name: sessionid
        in: path
        required: true
        schema:
          type: string
        description: The ID of the session to target.
    get:
      summary: Get session information
      operationId: get_db-_session-sessionid
      tags:
        - Session
      description: >
        Retrieve session information such as the user the session belongs too
        and what channels that user can access.
      responses:
        '200':
          description: Properties associated with a user session
          content:
            application/json:
              schema:
                type: object
                properties:
                  authentication_handlers:
                    description: >-
                      The ways authentication can be established to authenticate
                      as a user. Used for CouchDB compatibility. Always contains
                      "default" and "cookie".
                    type: array
                    enum:
                      - - default
                        - cookie
                    default:
                      - default
                      - cookie
                  ok:
                    description: Used for CouchDB compatibility. Always true.
                    type: boolean
                    enum:
                      - true
                  userCtx:
                    type: object
                    properties:
                      channels:
                        description: >-
                          A map of the channels in the default collection that
                          the user is in along with the sequence number the user
                          was granted access. This does not include inherited
                          channels through roles.
                        type: object
                        additionalProperties:
                          x-additionalPropertiesName: channelName
                          type: number
                          minimum: 1
                          description: The sequence number the user was granted access.
                          title: sequence number
                        example:
                          '!': 1
                          channelA: 2
                      name:
                        description: The name of the user.
                        type: string
                        minLength: 1
                    required:
                      - channels
                      - name
                required:
                  - authentication_handlers
                  - ok
                  - userCtx
                title: User Session Information
        '404':
          description: Resource could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
    delete:
      summary: Remove session
      operationId: delete_db-_session-sessionid
      tags:
        - Session
      description: >
        Invalidates the session provided so that anyone using it is logged out
        and is prevented from future use.
      responses:
        '200':
          description: Successfully removed the user session
        '404':
          description: Resource could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
  '/{db}/_user/{name}':
    parameters:
      - name: db
        in: path
        required: true
        schema:
          type: string
        example: db1
        description: The name of the database to run the operation against.
      - name: name
        in: path
        required: true
        schema:
          type: string
        description: The name of the user.
    get:
      summary: Get a user
      operationId: get_db-_user-name
      tags:
        - Database Security
      description: |
        Retrieve a single users information.
      responses:
        '200':
          description: Properties associated with a user
          content:
            application/json:
              schema:
                description: Properties associated with a user
                type: object
                properties:
                  name:
                    description: >-
                      The name of the user.


                      User names can only have alphanumeric ASCII characters and
                      underscores.
                    type: string
                  password:
                    description: >-
                      The password of the user.


                      Mandatory. unless `allow_empty_password` is `true` in the
                      database configs.
                    type: string
                  admin_channels:
                    description: >-
                      A list of channels to explicitly grant to the user for the
                      default collection.

                      See `collection_access` for channels in named collections.
                    type: array
                    items:
                      type: string
                  all_channels:
                    description: >-
                      All the channels that the user has been granted access to
                      for the default collection.

                      See `collection_access` for channels in named collections.


                      Access could have been granted through the sync function,
                      roles, or explicitly on the user under the
                      `admin_channels` property.
                    type: array
                    items:
                      type: string
                    readOnly: true
                  email:
                    description: The email address of the user.
                    type: string
                  disabled:
                    description: >-
                      If true, the user will not be able to login to the account
                      as it is disabled.
                    type: boolean
                    default: false
                  admin_roles:
                    description: A list of roles to explicitly grant to the user.
                    type: array
                    items:
                      type: string
                  roles:
                    description: >-
                      All the roles that the user has been granted access to.


                      Access could have been granted through the sync function,
                      roles_claim, or explicitly on the user under the
                      `admin_roles` property.
                    type: array
                    items:
                      type: string
                    readOnly: true
                  jwt_roles:
                    description: >-
                      The roles that the user has been added to through
                      roles_claim.
                    type: array
                    items:
                      type: string
                    readOnly: true
                  jwt_channels:
                    description: >-
                      The channels that the user has been granted access to
                      through channels_claim for the default collection.
                    type: array
                    items:
                      type: string
                    readOnly: true
                  jwt_issuer:
                    description: >-
                      The issuer of the last JSON Web Token that the user last
                      used to sign in.
                    type: string
                    readOnly: true
                  jwt_last_updated:
                    description: >-
                      The last time that the user's JWT roles/channels were
                      updated.
                    type: string
                    format: date-time
                    readOnly: true
                  collection_access:
                    description: >-
                      A set of access grants by scope and collection for a
                      specific collection.
                    type: object
                    additionalProperties:
                      maxProperties: 1
                      description: >-
                        An object keyed by scope, containing a set of
                        collections.
                      type: object
                      x-additionalPropertiesName: scopename
                      additionalProperties:
                        description: >-
                          An object keyed by collection name, defines access
                          collections in this scope.
                        type: object
                        x-additionalPropertiesName: collectionname
                        properties:
                          admin_channels:
                            description: >-
                              A list of channels to explicitly grant to the user
                              in this collection.
                            type: array
                            items:
                              type: string
                          all_channels:
                            description: >-
                              All the channels that the user has been granted
                              access to in this collection.


                              Access could have been granted through the sync
                              function, roles, or explicitly on the user under
                              the `admin_channels` property.
                            type: array
                            items:
                              type: string
                            readOnly: true
                          jwt_channels:
                            description: >-
                              The channels that the user has been granted access
                              to through channels_claim for this collection.
                            type: array
                            items:
                              type: string
                            readOnly: true
                          jwt_last_updated:
                            description: >-
                              The last time that the user's JWT channels were
                              updated for this collection.
                            type: string
                            format: date-time
                            readOnly: true
                title: User
        '404':
          description: Resource could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
    put:
      summary: Upsert a user
      description: >
        If the user does not exist, create a new user otherwise update the
        existing user.
      requestBody:
        content:
          application/json:
            schema:
              description: Properties associated with a user
              type: object
              properties:
                name:
                  description: >-
                    The name of the user.


                    User names can only have alphanumeric ASCII characters and
                    underscores.
                  type: string
                password:
                  description: >-
                    The password of the user.


                    Mandatory. unless `allow_empty_password` is `true` in the
                    database configs.
                  type: string
                admin_channels:
                  description: >-
                    A list of channels to explicitly grant to the user for the
                    default collection.

                    See `collection_access` for channels in named collections.
                  type: array
                  items:
                    type: string
                all_channels:
                  description: >-
                    All the channels that the user has been granted access to
                    for the default collection.

                    See `collection_access` for channels in named collections.


                    Access could have been granted through the sync function,
                    roles, or explicitly on the user under the `admin_channels`
                    property.
                  type: array
                  items:
                    type: string
                  readOnly: true
                email:
                  description: The email address of the user.
                  type: string
                disabled:
                  description: >-
                    If true, the user will not be able to login to the account
                    as it is disabled.
                  type: boolean
                  default: false
                admin_roles:
                  description: A list of roles to explicitly grant to the user.
                  type: array
                  items:
                    type: string
                roles:
                  description: >-
                    All the roles that the user has been granted access to.


                    Access could have been granted through the sync function,
                    roles_claim, or explicitly on the user under the
                    `admin_roles` property.
                  type: array
                  items:
                    type: string
                  readOnly: true
                jwt_roles:
                  description: >-
                    The roles that the user has been added to through
                    roles_claim.
                  type: array
                  items:
                    type: string
                  readOnly: true
                jwt_channels:
                  description: >-
                    The channels that the user has been granted access to
                    through channels_claim for the default collection.
                  type: array
                  items:
                    type: string
                  readOnly: true
                jwt_issuer:
                  description: >-
                    The issuer of the last JSON Web Token that the user last
                    used to sign in.
                  type: string
                  readOnly: true
                jwt_last_updated:
                  description: >-
                    The last time that the user's JWT roles/channels were
                    updated.
                  type: string
                  format: date-time
                  readOnly: true
                collection_access:
                  description: >-
                    A set of access grants by scope and collection for a
                    specific collection.
                  type: object
                  additionalProperties:
                    maxProperties: 1
                    description: 'An object keyed by scope, containing a set of collections.'
                    type: object
                    x-additionalPropertiesName: scopename
                    additionalProperties:
                      description: >-
                        An object keyed by collection name, defines access
                        collections in this scope.
                      type: object
                      x-additionalPropertiesName: collectionname
                      properties:
                        admin_channels:
                          description: >-
                            A list of channels to explicitly grant to the user
                            in this collection.
                          type: array
                          items:
                            type: string
                        all_channels:
                          description: >-
                            All the channels that the user has been granted
                            access to in this collection.


                            Access could have been granted through the sync
                            function, roles, or explicitly on the user under the
                            `admin_channels` property.
                          type: array
                          items:
                            type: string
                          readOnly: true
                        jwt_channels:
                          description: >-
                            The channels that the user has been granted access
                            to through channels_claim for this collection.
                          type: array
                          items:
                            type: string
                          readOnly: true
                        jwt_last_updated:
                          description: >-
                            The last time that the user's JWT channels were
                            updated for this collection.
                          type: string
                          format: date-time
                          readOnly: true
              title: User
        description: Properties associated with a user
      operationId: put_db-_user-name
      tags:
        - Database Security
      responses:
        '200':
          description: Existing user modified successfully
        '201':
          description: New user created
        '404':
          description: Resource could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
    delete:
      summary: Delete a user
      operationId: delete_db-_user-name
      tags:
        - Database Security
      description: |
        Delete a user from the database.
      responses:
        '200':
          description: User deleted successfully
        '404':
          description: Resource could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
    head:
      summary: Check if user exists
      operationId: head_db-_user-name
      tags:
        - Database Security
      description: |
        Check if the user exists by checking the status code.
      responses:
        '200':
          description: User exists
        '404':
          description: Not Found
  '/{db}/_user/{name}/_session':
    parameters:
      - name: db
        in: path
        required: true
        schema:
          type: string
        example: db1
        description: The name of the database to run the operation against.
      - name: name
        in: path
        required: true
        schema:
          type: string
        description: The name of the user.
    delete:
      summary: Remove all of a users sessions
      operationId: delete_db-_user-name-_session
      tags:
        - Session
      description: |
        Invalidates all the sessions that a user has.

        Will still return a `200` status code if the user has no sessions.
      responses:
        '200':
          description: User now has no sessions
        '404':
          description: Resource could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
  '/{db}/_user/{name}/_session/{sessionid}':
    parameters:
      - name: db
        in: path
        required: true
        schema:
          type: string
        example: db1
        description: The name of the database to run the operation against.
      - name: name
        in: path
        required: true
        schema:
          type: string
        description: The name of the user.
      - name: sessionid
        in: path
        required: true
        schema:
          type: string
        description: The ID of the session to target.
    delete:
      summary: Remove session with user validation
      operationId: delete_db-_user-name-_session-sessionid
      tags:
        - Session
      description: |
        Invalidates the session only if it belongs to the user.
      responses:
        '200':
          description: >-
            Session has been successfully removed as the user was associated
            with the session
        '404':
          description: Resource could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
  '/{db}/_role/':
    parameters:
      - name: db
        in: path
        required: true
        schema:
          type: string
        example: db1
        description: The name of the database to run the operation against.
    get:
      summary: Get all names of the roles
      operationId: get_db-_role-
      tags:
        - Database Security
      description: |
        Retrieves all the roles that are in the database.
      parameters:
        - name: deleted
          in: query
          description: >-
            Indicates that roles marked as deleted should be included in the
            result.
          schema:
            type: boolean
            default: false
            enum:
              - true
              - false
      responses:
        '200':
          description: Roles retrieved successfully
          content:
            application/json:
              schema:
                description: List of all role names
                type: array
                items:
                  type: string
                minItems: 0
                uniqueItems: true
              example:
                - Administrator
                - Moderator
        '404':
          description: Resource could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
    post:
      summary: Create a new role
      description: >
        Create a new role using the request body to specify the properties on
        the role.
      requestBody:
        content:
          application/json:
            schema:
              description: Properties associated with a role
              type: object
              properties:
                name:
                  description: >-
                    The name of the role.


                    Role names can only have alphanumeric ASCII characters and
                    underscores.
                  type: string
                admin_channels:
                  description: >-
                    A list of channels to explicitly grant to the role for the
                    default collection.

                    See `collection_access` for channels in named collections.
                  type: array
                  items:
                    type: string
                all_channels:
                  description: >-
                    All the channels that the role has been granted access to
                    for the default collection.


                    These channels could have been assigned by the Sync function
                    or using the `admin_channels` property.
                  type: array
                  items:
                    type: string
                  readOnly: true
                collection_access:
                  description: >-
                    A set of access grants by scope and collection for a
                    specific collection.
                  type: object
                  additionalProperties:
                    maxProperties: 1
                    description: 'An object keyed by scope, containing a set of collections.'
                    type: object
                    x-additionalPropertiesName: scopename
                    additionalProperties:
                      description: >-
                        An object keyed by collection name, defines access
                        collections in this scope.
                      type: object
                      x-additionalPropertiesName: collectionname
                      properties:
                        admin_channels:
                          description: >-
                            A list of channels to explicitly grant to the user
                            in this collection.
                          type: array
                          items:
                            type: string
                        all_channels:
                          description: >-
                            All the channels that the user has been granted
                            access to in this collection.


                            Access could have been granted through the sync
                            function, roles, or explicitly on the user under the
                            `admin_channels` property.
                          type: array
                          items:
                            type: string
                          readOnly: true
                        jwt_channels:
                          description: >-
                            The channels that the user has been granted access
                            to through channels_claim for this collection.
                          type: array
                          items:
                            type: string
                          readOnly: true
                        jwt_last_updated:
                          description: >-
                            The last time that the user's JWT channels were
                            updated for this collection.
                          type: string
                          format: date-time
                          readOnly: true
              title: Role
        description: Properties associated with a role
      operationId: post_db-_role-
      tags:
        - Database Security
      responses:
        '201':
          description: New role created successfully
        '404':
          description: Resource could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
        '409':
          description: Resource already exists under that name
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
  '/{db}/_role/{name}':
    parameters:
      - name: db
        in: path
        required: true
        schema:
          type: string
        example: db1
        description: The name of the database to run the operation against.
      - name: name
        in: path
        required: true
        schema:
          type: string
        description: The name of the role.
    get:
      summary: Get a role
      operationId: get_db-_role-name
      tags:
        - Database Security
      description: |
        Retrieve a single roles properties.
      responses:
        '200':
          description: Properties associated with a role
          content:
            application/json:
              schema:
                description: Properties associated with a role
                type: object
                properties:
                  name:
                    description: >-
                      The name of the role.


                      Role names can only have alphanumeric ASCII characters and
                      underscores.
                    type: string
                  admin_channels:
                    description: >-
                      A list of channels to explicitly grant to the role for the
                      default collection.

                      See `collection_access` for channels in named collections.
                    type: array
                    items:
                      type: string
                  all_channels:
                    description: >-
                      All the channels that the role has been granted access to
                      for the default collection.


                      These channels could have been assigned by the Sync
                      function or using the `admin_channels` property.
                    type: array
                    items:
                      type: string
                    readOnly: true
                  collection_access:
                    description: >-
                      A set of access grants by scope and collection for a
                      specific collection.
                    type: object
                    additionalProperties:
                      maxProperties: 1
                      description: >-
                        An object keyed by scope, containing a set of
                        collections.
                      type: object
                      x-additionalPropertiesName: scopename
                      additionalProperties:
                        description: >-
                          An object keyed by collection name, defines access
                          collections in this scope.
                        type: object
                        x-additionalPropertiesName: collectionname
                        properties:
                          admin_channels:
                            description: >-
                              A list of channels to explicitly grant to the user
                              in this collection.
                            type: array
                            items:
                              type: string
                          all_channels:
                            description: >-
                              All the channels that the user has been granted
                              access to in this collection.


                              Access could have been granted through the sync
                              function, roles, or explicitly on the user under
                              the `admin_channels` property.
                            type: array
                            items:
                              type: string
                            readOnly: true
                          jwt_channels:
                            description: >-
                              The channels that the user has been granted access
                              to through channels_claim for this collection.
                            type: array
                            items:
                              type: string
                            readOnly: true
                          jwt_last_updated:
                            description: >-
                              The last time that the user's JWT channels were
                              updated for this collection.
                            type: string
                            format: date-time
                            readOnly: true
                title: Role
        '404':
          description: Resource could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
    put:
      summary: Upsert a role
      description: >
        If the role does not exist, create a new role otherwise update the
        existing role.
      requestBody:
        content:
          application/json:
            schema:
              description: Properties associated with a role
              type: object
              properties:
                name:
                  description: >-
                    The name of the role.


                    Role names can only have alphanumeric ASCII characters and
                    underscores.
                  type: string
                admin_channels:
                  description: >-
                    A list of channels to explicitly grant to the role for the
                    default collection.

                    See `collection_access` for channels in named collections.
                  type: array
                  items:
                    type: string
                all_channels:
                  description: >-
                    All the channels that the role has been granted access to
                    for the default collection.


                    These channels could have been assigned by the Sync function
                    or using the `admin_channels` property.
                  type: array
                  items:
                    type: string
                  readOnly: true
                collection_access:
                  description: >-
                    A set of access grants by scope and collection for a
                    specific collection.
                  type: object
                  additionalProperties:
                    maxProperties: 1
                    description: 'An object keyed by scope, containing a set of collections.'
                    type: object
                    x-additionalPropertiesName: scopename
                    additionalProperties:
                      description: >-
                        An object keyed by collection name, defines access
                        collections in this scope.
                      type: object
                      x-additionalPropertiesName: collectionname
                      properties:
                        admin_channels:
                          description: >-
                            A list of channels to explicitly grant to the user
                            in this collection.
                          type: array
                          items:
                            type: string
                        all_channels:
                          description: >-
                            All the channels that the user has been granted
                            access to in this collection.


                            Access could have been granted through the sync
                            function, roles, or explicitly on the user under the
                            `admin_channels` property.
                          type: array
                          items:
                            type: string
                          readOnly: true
                        jwt_channels:
                          description: >-
                            The channels that the user has been granted access
                            to through channels_claim for this collection.
                          type: array
                          items:
                            type: string
                          readOnly: true
                        jwt_last_updated:
                          description: >-
                            The last time that the user's JWT channels were
                            updated for this collection.
                          type: string
                          format: date-time
                          readOnly: true
              title: Role
        description: Properties associated with a role
      operationId: put_db-_role-name
      tags:
        - Database Security
      responses:
        '200':
          description: OK
        '201':
          description: Created
        '404':
          description: Resource could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
    delete:
      summary: Delete a role
      operationId: delete_db-_role-name
      tags:
        - Database Security
      description: |
        Delete a role from the database.
      responses:
        '200':
          description: OK
        '404':
          description: Resource could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
    head:
      summary: Check if role exists
      operationId: head_db-_role-name
      tags:
        - Database Security
      description: |
        Check if the role exists by checking the status code.
      responses:
        '200':
          description: Role exists
        '404':
          description: Resource could not be found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: The error name.
                    type: string
                  reason:
                    description: The error description.
                    type: string
                required:
                  - error
                  - reason
                title: HTTP-Error
              example:
                error: not_found
                reason: no such database "invalid-db"
components:
  parameters:
    db:
      name: db
      in: path
      required: true
      schema:
        type: string
      example: db1
      description: The name of the database to run the operation against.
    sessionid:
      name: sessionid
      in: path
      required: true
      schema:
        type: string
      description: The ID of the session to target.
    user-name:
      name: name
      in: path
      required: true
      schema:
        type: string
      description: The name of the user.
    role-name:
      name: name
      in: path
      required: true
      schema:
        type: string
      description: The name of the role.
  schemas:
    User-session-information:
      type: object
      properties:
        authentication_handlers:
          description: >-
            The ways authentication can be established to authenticate as a
            user. Used for CouchDB compatibility. Always contains "default" and
            "cookie".
          type: array
          enum:
            - - default
              - cookie
          default:
            - default
            - cookie
        ok:
          description: Used for CouchDB compatibility. Always true.
          type: boolean
          enum:
            - true
        userCtx:
          type: object
          properties:
            channels:
              description: >-
                A map of the channels in the default collection that the user is
                in along with the sequence number the user was granted access.
                This does not include inherited channels through roles.
              type: object
              additionalProperties:
                x-additionalPropertiesName: channelName
                type: number
                minimum: 1
                description: The sequence number the user was granted access.
                title: sequence number
              example:
                '!': 1
                channelA: 2
            name:
              description: The name of the user.
              type: string
              minLength: 1
          required:
            - channels
            - name
      required:
        - authentication_handlers
        - ok
        - userCtx
      title: User Session Information
    HTTP-Error:
      type: object
      properties:
        error:
          description: The error name.
          type: string
        reason:
          description: The error description.
          type: string
      required:
        - error
        - reason
      title: HTTP-Error
    User:
      description: Properties associated with a user
      type: object
      properties:
        name:
          description: >-
            The name of the user.


            User names can only have alphanumeric ASCII characters and
            underscores.
          type: string
        password:
          description: >-
            The password of the user.


            Mandatory. unless `allow_empty_password` is `true` in the database
            configs.
          type: string
        admin_channels:
          description: >-
            A list of channels to explicitly grant to the user for the default
            collection.

            See `collection_access` for channels in named collections.
          type: array
          items:
            type: string
        all_channels:
          description: >-
            All the channels that the user has been granted access to for the
            default collection.

            See `collection_access` for channels in named collections.


            Access could have been granted through the sync function, roles, or
            explicitly on the user under the `admin_channels` property.
          type: array
          items:
            type: string
          readOnly: true
        email:
          description: The email address of the user.
          type: string
        disabled:
          description: >-
            If true, the user will not be able to login to the account as it is
            disabled.
          type: boolean
          default: false
        admin_roles:
          description: A list of roles to explicitly grant to the user.
          type: array
          items:
            type: string
        roles:
          description: >-
            All the roles that the user has been granted access to.


            Access could have been granted through the sync function,
            roles_claim, or explicitly on the user under the `admin_roles`
            property.
          type: array
          items:
            type: string
          readOnly: true
        jwt_roles:
          description: The roles that the user has been added to through roles_claim.
          type: array
          items:
            type: string
          readOnly: true
        jwt_channels:
          description: >-
            The channels that the user has been granted access to through
            channels_claim for the default collection.
          type: array
          items:
            type: string
          readOnly: true
        jwt_issuer:
          description: >-
            The issuer of the last JSON Web Token that the user last used to
            sign in.
          type: string
          readOnly: true
        jwt_last_updated:
          description: The last time that the user's JWT roles/channels were updated.
          type: string
          format: date-time
          readOnly: true
        collection_access:
          description: >-
            A set of access grants by scope and collection for a specific
            collection.
          type: object
          additionalProperties:
            maxProperties: 1
            description: 'An object keyed by scope, containing a set of collections.'
            type: object
            x-additionalPropertiesName: scopename
            additionalProperties:
              description: >-
                An object keyed by collection name, defines access collections
                in this scope.
              type: object
              x-additionalPropertiesName: collectionname
              properties:
                admin_channels:
                  description: >-
                    A list of channels to explicitly grant to the user in this
                    collection.
                  type: array
                  items:
                    type: string
                all_channels:
                  description: >-
                    All the channels that the user has been granted access to in
                    this collection.


                    Access could have been granted through the sync function,
                    roles, or explicitly on the user under the `admin_channels`
                    property.
                  type: array
                  items:
                    type: string
                  readOnly: true
                jwt_channels:
                  description: >-
                    The channels that the user has been granted access to
                    through channels_claim for this collection.
                  type: array
                  items:
                    type: string
                  readOnly: true
                jwt_last_updated:
                  description: >-
                    The last time that the user's JWT channels were updated for
                    this collection.
                  type: string
                  format: date-time
                  readOnly: true
      title: User
    Role:
      description: Properties associated with a role
      type: object
      properties:
        name:
          description: >-
            The name of the role.


            Role names can only have alphanumeric ASCII characters and
            underscores.
          type: string
        admin_channels:
          description: >-
            A list of channels to explicitly grant to the role for the default
            collection.

            See `collection_access` for channels in named collections.
          type: array
          items:
            type: string
        all_channels:
          description: >-
            All the channels that the role has been granted access to for the
            default collection.


            These channels could have been assigned by the Sync function or
            using the `admin_channels` property.
          type: array
          items:
            type: string
          readOnly: true
        collection_access:
          description: >-
            A set of access grants by scope and collection for a specific
            collection.
          type: object
          additionalProperties:
            maxProperties: 1
            description: 'An object keyed by scope, containing a set of collections.'
            type: object
            x-additionalPropertiesName: scopename
            additionalProperties:
              description: >-
                An object keyed by collection name, defines access collections
                in this scope.
              type: object
              x-additionalPropertiesName: collectionname
              properties:
                admin_channels:
                  description: >-
                    A list of channels to explicitly grant to the user in this
                    collection.
                  type: array
                  items:
                    type: string
                all_channels:
                  description: >-
                    All the channels that the user has been granted access to in
                    this collection.


                    Access could have been granted through the sync function,
                    roles, or explicitly on the user under the `admin_channels`
                    property.
                  type: array
                  items:
                    type: string
                  readOnly: true
                jwt_channels:
                  description: >-
                    The channels that the user has been granted access to
                    through channels_claim for this collection.
                  type: array
                  items:
                    type: string
                  readOnly: true
                jwt_last_updated:
                  description: >-
                    The last time that the user's JWT channels were updated for
                    this collection.
                  type: string
                  format: date-time
                  readOnly: true
      title: Role
  responses:
    User-session-information:
      description: Properties associated with a user session
      content:
        application/json:
          schema:
            type: object
            properties:
              authentication_handlers:
                description: >-
                  The ways authentication can be established to authenticate as
                  a user. Used for CouchDB compatibility. Always contains
                  "default" and "cookie".
                type: array
                enum:
                  - - default
                    - cookie
                default:
                  - default
                  - cookie
              ok:
                description: Used for CouchDB compatibility. Always true.
                type: boolean
                enum:
                  - true
              userCtx:
                type: object
                properties:
                  channels:
                    description: >-
                      A map of the channels in the default collection that the
                      user is in along with the sequence number the user was
                      granted access. This does not include inherited channels
                      through roles.
                    type: object
                    additionalProperties:
                      x-additionalPropertiesName: channelName
                      type: number
                      minimum: 1
                      description: The sequence number the user was granted access.
                      title: sequence number
                    example:
                      '!': 1
                      channelA: 2
                  name:
                    description: The name of the user.
                    type: string
                    minLength: 1
                required:
                  - channels
                  - name
            required:
              - authentication_handlers
              - ok
              - userCtx
            title: User Session Information
    Not-found:
      description: Resource could not be found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                description: The error name.
                type: string
              reason:
                description: The error description.
                type: string
            required:
              - error
              - reason
            title: HTTP-Error
          example:
            error: not_found
            reason: no such database "invalid-db"
    Unauthorized:
      description: 'User does not have access to resource, or resource does not exist'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                description: The error name.
                type: string
              reason:
                description: The error description.
                type: string
            required:
              - error
              - reason
            title: HTTP-Error
    User:
      description: Properties associated with a user
      content:
        application/json:
          schema:
            description: Properties associated with a user
            type: object
            properties:
              name:
                description: >-
                  The name of the user.


                  User names can only have alphanumeric ASCII characters and
                  underscores.
                type: string
              password:
                description: >-
                  The password of the user.


                  Mandatory. unless `allow_empty_password` is `true` in the
                  database configs.
                type: string
              admin_channels:
                description: >-
                  A list of channels to explicitly grant to the user for the
                  default collection.

                  See `collection_access` for channels in named collections.
                type: array
                items:
                  type: string
              all_channels:
                description: >-
                  All the channels that the user has been granted access to for
                  the default collection.

                  See `collection_access` for channels in named collections.


                  Access could have been granted through the sync function,
                  roles, or explicitly on the user under the `admin_channels`
                  property.
                type: array
                items:
                  type: string
                readOnly: true
              email:
                description: The email address of the user.
                type: string
              disabled:
                description: >-
                  If true, the user will not be able to login to the account as
                  it is disabled.
                type: boolean
                default: false
              admin_roles:
                description: A list of roles to explicitly grant to the user.
                type: array
                items:
                  type: string
              roles:
                description: >-
                  All the roles that the user has been granted access to.


                  Access could have been granted through the sync function,
                  roles_claim, or explicitly on the user under the `admin_roles`
                  property.
                type: array
                items:
                  type: string
                readOnly: true
              jwt_roles:
                description: The roles that the user has been added to through roles_claim.
                type: array
                items:
                  type: string
                readOnly: true
              jwt_channels:
                description: >-
                  The channels that the user has been granted access to through
                  channels_claim for the default collection.
                type: array
                items:
                  type: string
                readOnly: true
              jwt_issuer:
                description: >-
                  The issuer of the last JSON Web Token that the user last used
                  to sign in.
                type: string
                readOnly: true
              jwt_last_updated:
                description: The last time that the user's JWT roles/channels were updated.
                type: string
                format: date-time
                readOnly: true
              collection_access:
                description: >-
                  A set of access grants by scope and collection for a specific
                  collection.
                type: object
                additionalProperties:
                  maxProperties: 1
                  description: 'An object keyed by scope, containing a set of collections.'
                  type: object
                  x-additionalPropertiesName: scopename
                  additionalProperties:
                    description: >-
                      An object keyed by collection name, defines access
                      collections in this scope.
                    type: object
                    x-additionalPropertiesName: collectionname
                    properties:
                      admin_channels:
                        description: >-
                          A list of channels to explicitly grant to the user in
                          this collection.
                        type: array
                        items:
                          type: string
                      all_channels:
                        description: >-
                          All the channels that the user has been granted access
                          to in this collection.


                          Access could have been granted through the sync
                          function, roles, or explicitly on the user under the
                          `admin_channels` property.
                        type: array
                        items:
                          type: string
                        readOnly: true
                      jwt_channels:
                        description: >-
                          The channels that the user has been granted access to
                          through channels_claim for this collection.
                        type: array
                        items:
                          type: string
                        readOnly: true
                      jwt_last_updated:
                        description: >-
                          The last time that the user's JWT channels were
                          updated for this collection.
                        type: string
                        format: date-time
                        readOnly: true
            title: User
    Conflict:
      description: Resource already exists under that name
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                description: The error name.
                type: string
              reason:
                description: The error description.
                type: string
            required:
              - error
              - reason
            title: HTTP-Error
    Role:
      description: Properties associated with a role
      content:
        application/json:
          schema:
            description: Properties associated with a role
            type: object
            properties:
              name:
                description: >-
                  The name of the role.


                  Role names can only have alphanumeric ASCII characters and
                  underscores.
                type: string
              admin_channels:
                description: >-
                  A list of channels to explicitly grant to the role for the
                  default collection.

                  See `collection_access` for channels in named collections.
                type: array
                items:
                  type: string
              all_channels:
                description: >-
                  All the channels that the role has been granted access to for
                  the default collection.


                  These channels could have been assigned by the Sync function
                  or using the `admin_channels` property.
                type: array
                items:
                  type: string
                readOnly: true
              collection_access:
                description: >-
                  A set of access grants by scope and collection for a specific
                  collection.
                type: object
                additionalProperties:
                  maxProperties: 1
                  description: 'An object keyed by scope, containing a set of collections.'
                  type: object
                  x-additionalPropertiesName: scopename
                  additionalProperties:
                    description: >-
                      An object keyed by collection name, defines access
                      collections in this scope.
                    type: object
                    x-additionalPropertiesName: collectionname
                    properties:
                      admin_channels:
                        description: >-
                          A list of channels to explicitly grant to the user in
                          this collection.
                        type: array
                        items:
                          type: string
                      all_channels:
                        description: >-
                          All the channels that the user has been granted access
                          to in this collection.


                          Access could have been granted through the sync
                          function, roles, or explicitly on the user under the
                          `admin_channels` property.
                        type: array
                        items:
                          type: string
                        readOnly: true
                      jwt_channels:
                        description: >-
                          The channels that the user has been granted access to
                          through channels_claim for this collection.
                        type: array
                        items:
                          type: string
                        readOnly: true
                      jwt_last_updated:
                        description: >-
                          The last time that the user's JWT channels were
                          updated for this collection.
                        type: string
                        format: date-time
                        readOnly: true
            title: Role
  requestBodies:
    User:
      content:
        application/json:
          schema:
            description: Properties associated with a user
            type: object
            properties:
              name:
                description: >-
                  The name of the user.


                  User names can only have alphanumeric ASCII characters and
                  underscores.
                type: string
              password:
                description: >-
                  The password of the user.


                  Mandatory. unless `allow_empty_password` is `true` in the
                  database configs.
                type: string
              admin_channels:
                description: >-
                  A list of channels to explicitly grant to the user for the
                  default collection.

                  See `collection_access` for channels in named collections.
                type: array
                items:
                  type: string
              all_channels:
                description: >-
                  All the channels that the user has been granted access to for
                  the default collection.

                  See `collection_access` for channels in named collections.


                  Access could have been granted through the sync function,
                  roles, or explicitly on the user under the `admin_channels`
                  property.
                type: array
                items:
                  type: string
                readOnly: true
              email:
                description: The email address of the user.
                type: string
              disabled:
                description: >-
                  If true, the user will not be able to login to the account as
                  it is disabled.
                type: boolean
                default: false
              admin_roles:
                description: A list of roles to explicitly grant to the user.
                type: array
                items:
                  type: string
              roles:
                description: >-
                  All the roles that the user has been granted access to.


                  Access could have been granted through the sync function,
                  roles_claim, or explicitly on the user under the `admin_roles`
                  property.
                type: array
                items:
                  type: string
                readOnly: true
              jwt_roles:
                description: The roles that the user has been added to through roles_claim.
                type: array
                items:
                  type: string
                readOnly: true
              jwt_channels:
                description: >-
                  The channels that the user has been granted access to through
                  channels_claim for the default collection.
                type: array
                items:
                  type: string
                readOnly: true
              jwt_issuer:
                description: >-
                  The issuer of the last JSON Web Token that the user last used
                  to sign in.
                type: string
                readOnly: true
              jwt_last_updated:
                description: The last time that the user's JWT roles/channels were updated.
                type: string
                format: date-time
                readOnly: true
              collection_access:
                description: >-
                  A set of access grants by scope and collection for a specific
                  collection.
                type: object
                additionalProperties:
                  maxProperties: 1
                  description: 'An object keyed by scope, containing a set of collections.'
                  type: object
                  x-additionalPropertiesName: scopename
                  additionalProperties:
                    description: >-
                      An object keyed by collection name, defines access
                      collections in this scope.
                    type: object
                    x-additionalPropertiesName: collectionname
                    properties:
                      admin_channels:
                        description: >-
                          A list of channels to explicitly grant to the user in
                          this collection.
                        type: array
                        items:
                          type: string
                      all_channels:
                        description: >-
                          All the channels that the user has been granted access
                          to in this collection.


                          Access could have been granted through the sync
                          function, roles, or explicitly on the user under the
                          `admin_channels` property.
                        type: array
                        items:
                          type: string
                        readOnly: true
                      jwt_channels:
                        description: >-
                          The channels that the user has been granted access to
                          through channels_claim for this collection.
                        type: array
                        items:
                          type: string
                        readOnly: true
                      jwt_last_updated:
                        description: >-
                          The last time that the user's JWT channels were
                          updated for this collection.
                        type: string
                        format: date-time
                        readOnly: true
            title: User
      description: Properties associated with a user
    Role:
      content:
        application/json:
          schema:
            description: Properties associated with a role
            type: object
            properties:
              name:
                description: >-
                  The name of the role.


                  Role names can only have alphanumeric ASCII characters and
                  underscores.
                type: string
              admin_channels:
                description: >-
                  A list of channels to explicitly grant to the role for the
                  default collection.

                  See `collection_access` for channels in named collections.
                type: array
                items:
                  type: string
              all_channels:
                description: >-
                  All the channels that the role has been granted access to for
                  the default collection.


                  These channels could have been assigned by the Sync function
                  or using the `admin_channels` property.
                type: array
                items:
                  type: string
                readOnly: true
              collection_access:
                description: >-
                  A set of access grants by scope and collection for a specific
                  collection.
                type: object
                additionalProperties:
                  maxProperties: 1
                  description: 'An object keyed by scope, containing a set of collections.'
                  type: object
                  x-additionalPropertiesName: scopename
                  additionalProperties:
                    description: >-
                      An object keyed by collection name, defines access
                      collections in this scope.
                    type: object
                    x-additionalPropertiesName: collectionname
                    properties:
                      admin_channels:
                        description: >-
                          A list of channels to explicitly grant to the user in
                          this collection.
                        type: array
                        items:
                          type: string
                      all_channels:
                        description: >-
                          All the channels that the user has been granted access
                          to in this collection.


                          Access could have been granted through the sync
                          function, roles, or explicitly on the user under the
                          `admin_channels` property.
                        type: array
                        items:
                          type: string
                        readOnly: true
                      jwt_channels:
                        description: >-
                          The channels that the user has been granted access to
                          through channels_claim for this collection.
                        type: array
                        items:
                          type: string
                        readOnly: true
                      jwt_last_updated:
                        description: >-
                          The last time that the user's JWT channels were
                          updated for this collection.
                        type: string
                        format: date-time
                        readOnly: true
            title: Role
      description: Properties associated with a role

