Bernstein Authentication API

openapi: 3.2.0
info:
  title: Bernstein Task Server Authentication API
  description: 'Bernstein REST API - the open-source governance layer for AI agents, one git worktree per task.


    ## Authentication


    Authentication is ENABLED by default. Include a Bearer token in all requests:


    ```

    Authorization: Bearer

    ```


    To run without auth (development only), set `BERNSTEIN_AUTH_DISABLED=1` - this logs a loud warning and passes every request through.


    Public endpoints (no auth required): `/health`, `/health/ready`, `/health/live`, `/ready`, `/alive`, `/.well-known/agent.json`, `/docs`, `/openapi.json`, and the auth-flow endpoints (`/auth/login`, `/auth/oidc/callback`, etc.).


    Webhook and hook endpoints (`/webhook`, `/webhooks/*`, `/hooks/{session_id}`) authenticate via HMAC-SHA256 signatures - they do NOT accept Bearer tokens.


    ## Base URL


    Default: `http://127.0.0.1:8052`. Override with env vars `BERNSTEIN_HOST` and `BERNSTEIN_PORT`.


    ## Error Format


    All errors return JSON with a `detail` field:


    ```json

    {"detail": "Task not found: task-xyz"}

    ```


    | Status | Meaning |

    |--------|---------|

    | 400 | Bad request (validation error) |

    | 401 | Unauthorized (missing/invalid token) |

    | 403 | Forbidden (IP not in allowlist) |

    | 404 | Resource not found |

    | 409 | Conflict (task already in terminal state) |

    | 429 | Rate limited - respect the `Retry-After` header |

    | 500 | Internal server error |'
  version: 3.22.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: Alex Chernysh
    url: https://github.com/sipyourdrink-ltd/bernstein
servers:
- url: http://{host}:{port}
  description: Task server started by the Bernstein CLI on the operator's own machine. There is no hosted instance; substitute the host and port of your install.
  variables:
    host:
      default: 127.0.0.1
      description: Interface the task server binds to. Loopback by default.
    port:
      default: '8052'
      description: Task server port. Override with BERNSTEIN_PORT.
tags:
- name: Authentication
paths:
  /auth/providers:
    get:
      tags:
      - Authentication
      summary: Auth Providers
      description: List available authentication providers.
      operationId: auth_providers_auth_providers_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthProvidersResponse'
  /auth/login:
    get:
      tags:
      - Authentication
      summary: Login
      description: Initiate SSO login. Redirects to IdP.
      operationId: login_auth_login_get
      parameters:
      - name: provider
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/LoginProvider'
          default: oidc
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Authentication provider not enabled
        '404':
          description: SSO authentication is not configured on this server
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/oidc/callback:
    get:
      tags:
      - Authentication
      summary: Oidc Callback
      description: OIDC authorization code callback.
      operationId: oidc_callback_auth_oidc_callback_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Missing or invalid authorization code or state
        '404':
          description: SSO authentication is not configured on this server
  /auth/saml/acs:
    post:
      tags:
      - Authentication
      summary: Saml Acs
      description: 'SAML Assertion Consumer Service (ACS) endpoint.


        Receives the SAML Response from the IdP via HTTP-POST binding.'
      operationId: saml_acs_auth_saml_acs_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Missing SAMLResponse
        '404':
          description: SSO authentication is not configured on this server
  /auth/saml/metadata:
    get:
      tags:
      - Authentication
      summary: Saml Metadata
      description: SAML SP metadata endpoint for IdP configuration.
      operationId: saml_metadata_auth_saml_metadata_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: SSO authentication is not configured on this server
  /auth/cli/device:
    post:
      tags:
      - Authentication
      summary: Device Code Request
      description: 'Initiate device authorization flow for CLI login.


        The CLI calls this to get a device_code and user_code.

        The user enters the user_code in the web dashboard after SSO login

        to authorize the CLI session.'
      operationId: device_code_request_auth_cli_device_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceCodeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceCodeResponse'
        '404':
          description: SSO authentication is not configured on this server
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/cli/token:
    post:
      tags:
      - Authentication
      summary: Device Token Poll
      description: 'Poll for device authorization status.


        Returns the access token once the user has authorized the device code.'
      operationId: device_token_poll_auth_cli_token_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DevicePollRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevicePollResponse'
        '404':
          description: SSO authentication is not configured on this server
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/cli/authorize:
    post:
      tags:
      - Authentication
      summary: Device Authorize
      description: 'Authorize a device code (called from web dashboard after SSO login).


        Requires an authenticated user session.'
      operationId: device_authorize_auth_cli_authorize_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceAuthorizeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Invalid or expired user code
        '401':
          description: Authentication required
        '404':
          description: SSO authentication is not configured on this server
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/me:
    get:
      tags:
      - Authentication
      summary: Get Profile
      description: Get the current authenticated user's profile.
      operationId: get_profile_auth_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfileResponse'
        '401':
          description: Authentication required
  /auth/logout:
    post:
      tags:
      - Authentication
      summary: Logout
      description: Logout and revoke the current session.
      operationId: logout_auth_logout_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: SSO authentication is not configured on this server
  /auth/group-mappings:
    get:
      tags:
      - Authentication
      summary: Get Group Mappings
      description: Get current SSO group → role mappings.
      operationId: get_group_mappings_auth_group_mappings_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMappingsResponse'
        '404':
          description: SSO authentication is not configured on this server
    put:
      tags:
      - Authentication
      summary: Update Group Mappings
      description: Update SSO group → role mappings (admin only).
      operationId: update_group_mappings_auth_group_mappings_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupMappingsUpdateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Invalid role value
        '401':
          description: Authentication required
        '403':
          description: Admin role required
        '404':
          description: SSO authentication is not configured on this server
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/users:
    get:
      tags:
      - Authentication
      summary: List Users
      description: List all users (admin only).
      operationId: list_users_auth_users_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Authentication required
        '403':
          description: Admin role required
        '404':
          description: SSO authentication is not configured on this server
  /api/v1/auth/providers:
    get:
      tags:
      - Authentication
      summary: Auth Providers
      description: List available authentication providers.
      operationId: auth_providers_api_v1_auth_providers_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthProvidersResponse'
  /api/v1/auth/login:
    get:
      tags:
      - Authentication
      summary: Login
      description: Initiate SSO login. Redirects to IdP.
      operationId: login_api_v1_auth_login_get
      parameters:
      - name: provider
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/LoginProvider'
          default: oidc
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Authentication provider not enabled
        '404':
          description: SSO authentication is not configured on this server
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/auth/oidc/callback:
    get:
      tags:
      - Authentication
      summary: Oidc Callback
      description: OIDC authorization code callback.
      operationId: oidc_callback_api_v1_auth_oidc_callback_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Missing or invalid authorization code or state
        '404':
          description: SSO authentication is not configured on this server
  /api/v1/auth/saml/acs:
    post:
      tags:
      - Authentication
      summary: Saml Acs
      description: 'SAML Assertion Consumer Service (ACS) endpoint.


        Receives the SAML Response from the IdP via HTTP-POST binding.'
      operationId: saml_acs_api_v1_auth_saml_acs_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Missing SAMLResponse
        '404':
          description: SSO authentication is not configured on this server
  /api/v1/auth/saml/metadata:
    get:
      tags:
      - Authentication
      summary: Saml Metadata
      description: SAML SP metadata endpoint for IdP configuration.
      operationId: saml_metadata_api_v1_auth_saml_metadata_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: SSO authentication is not configured on this server
  /api/v1/auth/cli/device:
    post:
      tags:
      - Authentication
      summary: Device Code Request
      description: 'Initiate device authorization flow for CLI login.


        The CLI calls this to get a device_code and user_code.

        The user enters the user_code in the web dashboard after SSO login

        to authorize the CLI session.'
      operationId: device_code_request_api_v1_auth_cli_device_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceCodeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceCodeResponse'
        '404':
          description: SSO authentication is not configured on this server
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/auth/cli/token:
    post:
      tags:
      - Authentication
      summary: Device Token Poll
      description: 'Poll for device authorization status.


        Returns the access token once the user has authorized the device code.'
      operationId: device_token_poll_api_v1_auth_cli_token_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DevicePollRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevicePollResponse'
        '404':
          description: SSO authentication is not configured on this server
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/auth/cli/authorize:
    post:
      tags:
      - Authentication
      summary: Device Authorize
      description: 'Authorize a device code (called from web dashboard after SSO login).


        Requires an authenticated user session.'
      operationId: device_authorize_api_v1_auth_cli_authorize_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceAuthorizeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Invalid or expired user code
        '401':
          description: Authentication required
        '404':
          description: SSO authentication is not configured on this server
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/auth/me:
    get:
      tags:
      - Authentication
      summary: Get Profile
      description: Get the current authenticated user's profile.
      operationId: get_profile_api_v1_auth_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfileResponse'
        '401':
          description: Authentication required
  /api/v1/auth/logout:
    post:
      tags:
      - Authentication
      summary: Logout
      description: Logout and revoke the current session.
      operationId: logout_api_v1_auth_logout_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: SSO authentication is not configured on this server
  /api/v1/auth/group-mappings:
    get:
      tags:
      - Authentication
      summary: Get Group Mappings
      description: Get current SSO group → role mappings.
      operationId: get_group_mappings_api_v1_auth_group_mappings_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMappingsResponse'
        '404':
          description: SSO authentication is not configured on this server
    put:
      tags:
      - Authentication
      summary: Update Group Mappings
      description: Update SSO group → role mappings (admin only).
      operationId: update_group_mappings_api_v1_auth_group_mappings_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupMappingsUpdateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Invalid role value
        '401':
          description: Authentication required
        '403':
          description: Admin role required
        '404':
          description: SSO authentication is not configured on this server
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/auth/users:
    get:
      tags:
      - Authentication
      summary: List Users
      description: List all users (admin only).
      operationId: list_users_api_v1_auth_users_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Authentication required
        '403':
          description: Admin role required
        '404':
          description: SSO authentication is not configured on this server
components:
  schemas:
    DevicePollResponse:
      properties:
        access_token:
          type: string
          title: Access Token
          default: ''
        expires_at:
          anyOf:
          - type: number
          - type: 'null'
          title: Expires At
        refresh_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Refresh Token
        token_type:
          type: string
          title: Token Type
          default: Bearer
        status:
          type: string
          title: Status
          default: pending
      type: object
      title: DevicePollResponse
      description: Response for device token poll.
    UserProfileResponse:
      properties:
        id:
          type: string
          title: Id
        email:
          type: string
          title: Email
        display_name:
          type: string
          title: Display Name
        role:
          type: string
          title: Role
        sso_provider:
          type: string
          title: Sso Provider
        sso_groups:
          items:
            type: string
          type: array
          title: Sso Groups
        permissions:
          items:
            type: string
          type: array
          title: Permissions
      type: object
      required:
      - id
      - email
      - display_name
      - role
      - sso_provider
      - sso_groups
      - permissions
      title: UserProfileResponse
      description: Response for GET /auth/me.
    DeviceCodeRequest:
      properties:
        client_name:
          type: string
          title: Client Name
          default: bernstein-cli
      type: object
      title: DeviceCodeRequest
      description: Body for POST /auth/cli/device - initiate device auth flow.
    DeviceCodeResponse:
      properties:
        device_code:
          type: string
          title: Device Code
        user_code:
          type: string
          title: User Code
        verification_uri:
          type: string
          title: Verification Uri
        expires_in:
          type: integer
          title: Expires In
        interval:
          type: integer
          title: Interval
      type: object
      required:
      - device_code
      - user_code
      - verification_uri
      - expires_in
      - interval
      title: DeviceCodeResponse
      description: Response for device code request.
    LoginProvider:
      type: string
      enum:
      - oidc
      - saml
      title: LoginProvider
      description: 'SSO providers accepted by ``GET /auth/login``.


        Typing the ``provider`` query param with this enum lets FastAPI

        reject unknown values with a ``422`` at the validation layer instead

        of the handler falling through to a generic error for an input it

        was never going to support.'
    DevicePollRequest:
      properties:
        device_code:
          type: string
          title: Device Code
        grant_type:
          type: string
          title: Grant Type
          default: urn:ietf:params:oauth:grant-type:device_code
      type: object
      required:
      - device_code
      title: DevicePollRequest
      description: Body for POST /auth/cli/token - poll for device authorization.
    DeviceAuthorizeRequest:
      properties:
        user_code:
          type: string
          title: User Code
      type: object
      required:
      - user_code
      title: DeviceAuthorizeRequest
      description: Body for POST /auth/cli/authorize - authorize a device code.
    AuthProvidersResponse:
      properties:
        oidc_enabled:
          type: boolean
          title: Oidc Enabled
          default: false
        saml_enabled:
          type: boolean
          title: Saml Enabled
          default: false
        legacy_token_enabled:
          type: boolean
          title: Legacy Token Enabled
          default: false
        device_flow_enabled:
          type: boolean
          title: Device Flow Enabled
          default: true
      type: object
      title: AuthProvidersResponse
      description: Available authentication providers.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    GroupMappingEntry:
      properties:
        group:
          type: string
          title: Group
        role:
          type: string
          title: Role
      type: object
      required:
      - group
      - role
      title: GroupMappingEntry
      description: A single group → role mapping.
    GroupMappingsUpdateRequest:
      properties:
        mappings:
          items:
            $ref: '#/components/schemas/GroupMappingEntry'
          type: array
          title: Mappings
      type: object
      required:
      - mappings
      title: GroupMappingsUpdateRequest
      description: Body for PUT /auth/group-mappings.
    GroupMappingsResponse:
      properties:
        mappings:
          items:
            $ref: '#/components/schemas/GroupMappingEntry'
          type: array
          title: Mappings
      type: object
      required:
      - mappings
      title: GroupMappingsResponse
      description: Response for GET /auth/group-mappings.