Cockroach Labs 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. It is available on the same HTTP port used by the DB Console, defaulting to port 8080, and exposes endpoints under the /api/v2 base path. The API enables monitoring and troubleshooting workflows using any HTTP-capable tooling. Authentication requires requesting a session token via the /api/v2/login/ endpoint and passing it with subsequent requests using the X-Cockroach-API-Session header.
  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:
  schemas:
    Error:
      type: object
      description: Standard error response returned by the Cluster API.
      properties:
        error:
          type: string
          description: Human-readable description of the error.
    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
    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.
    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.
  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'
  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