CockroachDB Auth API

openapi: 3.2.0
info:
  title: CockroachDB Cluster Auth API
  description: The CockroachDB Cluster API is a REST API hosted by all nodes of a CockroachDB cluster that provides programmatic access to cluster status, node information, session data, range details, and alerting rules.
  version: 2.0.0
  contact:
    name: Cockroach Labs Support
    url: https://support.cockroachlabs.com
  termsOfService: https://www.cockroachlabs.com/cloud-terms-and-conditions/
servers:
- url: https://localhost:8080
  description: CockroachDB node HTTP port. Replace localhost with the host and 8080 with the configured --http-port of the target node.
security:
- sessionAuth: []
tags:
- name: Auth
  description: Authenticate to the Cluster API by creating and terminating API sessions. Session tokens are passed via the X-Cockroach-API-Session header on subsequent requests.
paths:
  /api/v2/login/:
    post:
      operationId: Login
      summary: Create a session
      description: Creates an authenticated API session by supplying valid SQL username and password credentials. Returns a session token in the X-Cockroach-API-Session response header. This token must be included as the X-Cockroach-API-Session header on all subsequent requests to authenticated endpoints.
      tags:
      - Auth
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Session created successfully. The session token is returned in the X-Cockroach-API-Session response header.
          headers:
            X-Cockroach-API-Session:
              description: Session token to use for authenticating subsequent requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/logout/:
    post:
      operationId: Logout
      summary: Terminate a session
      description: Terminates a previously established API session, invalidating the session token. The X-Cockroach-API-Session header must be included with the session token to revoke.
      tags:
      - Auth
      responses:
        '200':
          description: Session terminated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogoutResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Authentication is required. The X-Cockroach-API-Session header is missing or the session has expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    LoginRequest:
      type: object
      description: Credentials for authenticating to the Cluster API.
      required:
      - username
      - password
      properties:
        username:
          type: string
          description: SQL username to authenticate with.
        password:
          type: string
          description: Password for the SQL user.
          format: password
    Error:
      type: object
      description: Standard error response returned by the Cluster API.
      properties:
        error:
          type: string
          description: Human-readable description of the error.
    LoginResponse:
      type: object
      description: Response from a successful login request.
      properties:
        session:
          type: string
          description: Session token. Also returned in the X-Cockroach-API-Session response header for convenience.
    LogoutResponse:
      type: object
      description: Response from a logout request confirming session termination.
      properties:
        logged_out:
          type: boolean
          description: True if the session was successfully terminated.
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: header
      name: X-Cockroach-API-Session
      description: Session token obtained from the /api/v2/login/ endpoint. Include this header with all authenticated requests.
externalDocs:
  description: CockroachDB Cluster API Documentation
  url: https://www.cockroachlabs.com/docs/stable/cluster-api