Couchbase User Management API

openapi: 3.2.0
info:
  title: Couchbase Sync Gateway Admin REST User Management API
  description: The Couchbase Sync Gateway Admin REST API provides administrative endpoints for configuring and managing Sync Gateway instances. It supports database management, user and role administration, sync function configuration, and replication setup. The API is intended for server-side administration and is typically bound to localhost for security, enabling full control over Sync Gateway behavior, access control policies, and data synchronization rules.
  version: '3.1'
  contact:
    name: Couchbase Support
    url: https://support.couchbase.com
  termsOfService: https://www.couchbase.com/terms-of-use
servers:
- url: https://localhost:4985
  description: Sync Gateway Admin REST API (default port)
security:
- basicAuth: []
tags:
- name: User Management
  description: Endpoints for managing Sync Gateway users and their access permissions.
paths:
  /{db}/_user/:
    get:
      operationId: listUsers
      summary: List all users
      description: Returns the list of all users configured for the database.
      tags:
      - User Management
      parameters:
      - $ref: '#/components/parameters/db'
      responses:
        '200':
          description: Successful retrieval of user list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          description: Unauthorized access
    post:
      operationId: createUser
      summary: Create a user
      description: Creates a new user with the specified credentials, roles, and channel assignments.
      tags:
      - User Management
      parameters:
      - $ref: '#/components/parameters/db'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserConfig'
      responses:
        '201':
          description: User created successfully
        '400':
          description: Invalid user configuration
        '401':
          description: Unauthorized access
        '409':
          description: User already exists
  /{db}/_user/{userName}:
    get:
      operationId: getUser
      summary: Get user details
      description: Returns detailed information about a user including their roles, channels, and admin channels.
      tags:
      - User Management
      parameters:
      - $ref: '#/components/parameters/db'
      - $ref: '#/components/parameters/userName'
      responses:
        '200':
          description: Successful retrieval of user details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '401':
          description: Unauthorized access
        '404':
          description: User not found
    put:
      operationId: updateUser
      summary: Update a user
      description: Updates a user's configuration including password, roles, and channels.
      tags:
      - User Management
      parameters:
      - $ref: '#/components/parameters/db'
      - $ref: '#/components/parameters/userName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserConfig'
      responses:
        '200':
          description: User updated successfully
        '401':
          description: Unauthorized access
        '404':
          description: User not found
    delete:
      operationId: deleteUser
      summary: Delete a user
      description: Deletes the specified user.
      tags:
      - User Management
      parameters:
      - $ref: '#/components/parameters/db'
      - $ref: '#/components/parameters/userName'
      responses:
        '200':
          description: User deleted successfully
        '401':
          description: Unauthorized access
        '404':
          description: User not found
  /{db}/_user/{userName}/_session:
    post:
      operationId: createUserSession
      summary: Create a session for a user
      description: Creates a new session for the specified user with an optional expiration time and channel override.
      tags:
      - User Management
      parameters:
      - $ref: '#/components/parameters/db'
      - $ref: '#/components/parameters/userName'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                ttl:
                  type: integer
                  description: Session time-to-live in seconds
      responses:
        '200':
          description: Session created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id:
                    type: string
                  expires:
                    type: string
                    format: date-time
                  cookie_name:
                    type: string
        '401':
          description: Unauthorized access
        '404':
          description: User not found
components:
  parameters:
    userName:
      name: userName
      in: path
      required: true
      description: The username
      schema:
        type: string
    db:
      name: db
      in: path
      required: true
      description: The database name
      schema:
        type: string
  schemas:
    UserInfo:
      type: object
      description: User information
      properties:
        name:
          type: string
        admin_channels:
          type: array
          items:
            type: string
        admin_roles:
          type: array
          items:
            type: string
        all_channels:
          type: array
          items:
            type: string
        roles:
          type: array
          items:
            type: string
        email:
          type: string
        disabled:
          type: boolean
    UserConfig:
      type: object
      description: User configuration
      required:
      - name
      properties:
        name:
          type: string
          description: Username
        password:
          type: string
          description: User password
        admin_channels:
          type: array
          description: Admin-assigned channels
          items:
            type: string
        admin_roles:
          type: array
          description: Admin-assigned roles
          items:
            type: string
        email:
          type: string
          format: email
          description: User email
        disabled:
          type: boolean
          description: Whether the user is disabled
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication with admin credentials or RBAC user with appropriate roles.
externalDocs:
  description: Couchbase Sync Gateway Admin REST API Documentation
  url: https://docs.couchbase.com/sync-gateway/current/rest-api-admin.html