chatrail-dev Auth API

openapi: 3.2.0
info:
  title: ChatRail Auth API
  version: 1.0.0
  description: 'Send, schedule and receive WhatsApp messages through a linked-device session.


    **Two things the API is careful about, which shape every endpoint below.**


    *Accepted is not delivered.* A 202 means the message is durably stored and queued. Only the `status` field ever claims WhatsApp delivered anything, and `queued`, `submitted`, `sent`, `delivered` and `read` are deliberately distinct.


    *A retry must not send twice.* Send `Idempotency-Key` on every send. A replay returns the original response; a concurrent duplicate is told to retry rather than allowed to race.'
  contact:
    name: ChatRail
    url: https://www.chatrail.dev
servers:
- url: https://www.chatrail.dev
security:
- apiKey: []
tags:
- name: Auth
  description: Dashboard sign-in. Not used by API clients.
paths:
  /v1/profile:
    get:
      summary: Read the signed-in profile
      tags:
      - Auth
      operationId: get_v1_profile
      responses:
        '200':
          description: Personal account details.
        '401':
          description: Not signed in.
      security:
      - session: []
    patch:
      summary: Update the display name
      tags:
      - Auth
      operationId: patch_v1_profile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 120
              required:
              - name
              additionalProperties: false
            example:
              name: Ada Lovelace
      responses:
        '200':
          description: The updated profile.
        '400':
          description: The name is empty or too long.
      security:
      - session: []
  /v1/profile/sessions:
    get:
      summary: List active account sessions
      description: Lists only the signed-in user’s live sessions and never exposes session tokens.
      tags:
      - Auth
      operationId: get_v1_profile_sessions
      responses:
        '200':
          description: Active device sessions, with the current session marked.
      security:
      - session: []
  /v1/profile/sessions/revoke-others:
    post:
      summary: Sign out other devices
      tags:
      - Auth
      operationId: post_v1_profile_sessions_revoke-others
      responses:
        '200':
          description: The number of other sessions revoked.
      security:
      - session: []
  /v1/profile/sessions/{sessionId}:
    delete:
      summary: Sign out a device
      description: A session belonging to another user is reported as not found.
      tags:
      - Auth
      operationId: delete_v1_profile_sessions__sessionId_
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
        description: Session id.
      responses:
        '204':
          description: Revoked.
        '404':
          description: No such active session.
      security:
      - session: []
  /v1/profile/notification-preferences:
    get:
      summary: Read notification preferences
      tags:
      - Auth
      operationId: get_v1_profile_notification-preferences
      responses:
        '200':
          description: The signed-in user’s email notification preferences.
      security:
      - session: []
    patch:
      summary: Update notification preferences
      tags:
      - Auth
      operationId: patch_v1_profile_notification-preferences
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                security:
                  type: boolean
                connectionFailures:
                  type: boolean
                deliveryProblems:
                  type: boolean
                aiLimits:
                  type: boolean
                billingUsage:
                  type: boolean
                onboarding:
                  type: boolean
              additionalProperties: false
            example:
              deliveryProblems: false
              aiLimits: true
      responses:
        '200':
          description: The updated preferences.
        '400':
          description: The update was empty or unknown.
      security:
      - session: []
  /v1/profile/heard-from:
    put:
      summary: Record how you heard about ChatRail
      description: Asked once on the getting-started page. `skipped` records a dismissal so the question is not shown again. Answering again replaces the answer.
      tags:
      - Auth
      operationId: put_v1_profile_heard-from
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                source:
                  type: string
                  enum:
                  - google
                  - ai_assistant
                  - x
                  - linkedin
                  - youtube
                  - reddit
                  - github
                  - n8n
                  - friend
                  - other
                  - skipped
                detail:
                  type: string
                  maxLength: 200
              required:
              - source
              additionalProperties: false
            example:
              source: linkedin
              detail: A post about WhatsApp bots
      responses:
        '200':
          description: The updated profile.
        '400':
          description: The source was not one of the listed values.
      security:
      - session: []
  /v1/auth/request-code:
    post:
      summary: Request a sign-in code
      description: Always answers 202, whether or not the address has an account. It is not an existence check and must not be presented as one.
      tags:
      - Auth
      operationId: post_v1_auth_request-code
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  maxLength: 320
                  format: email
                  pattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
              required:
              - email
              additionalProperties: false
            example:
              email: you@company.com
      responses:
        '202':
          description: A code has been sent if that address has an account.
      security: []
  /v1/auth/verify:
    post:
      summary: Exchange a code for a session
      description: Every failure returns the same error — no code, wrong code, expired, too many attempts. Distinguishing them would reintroduce an oracle.
      tags:
      - Auth
      operationId: post_v1_auth_verify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  maxLength: 320
                  format: email
                  pattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                code:
                  type: string
                  pattern: ^\d{6}$
              required:
              - email
              - code
              additionalProperties: false
            example:
              email: you@company.com
              code: '123456'
      responses:
        '200':
          description: A session cookie is set.
        '401':
          description: That code is not valid.
      security: []
  /v1/auth/session:
    get:
      summary: Read the current session
      tags:
      - Auth
      operationId: get_v1_auth_session
      responses:
        '200':
          description: The signed-in user and workspace.
        '401':
          description: Not signed in.
      security:
      - session: []
  /v1/auth/logout:
    post:
      summary: End the session
      tags:
      - Auth
      operationId: post_v1_auth_logout
      responses:
        '204':
          description: Signed out.
      security:
      - session: []
  /v1/auth/providers:
    get:
      summary: List sign-in providers
      description: Which of Google and GitHub are switched on for this deployment, so a sign-in page only offers buttons that will work.
      tags:
      - Auth
      operationId: get_v1_auth_providers
      responses:
        '200':
          description: An object of provider name to boolean.
      security: []
  /v1/auth/oauth/{provider}/start:
    get:
      summary: Start a Google or GitHub sign-in
      description: 'A browser navigation, not an API call: redirects to the provider with a state value and a PKCE challenge held in a short-lived HttpOnly cookie. An optional same-origin `next` path is where the person lands afterwards.'
      tags:
      - Auth
      operationId: get_v1_auth_oauth__provider__start
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
        description: '`google` or `github`.'
      responses:
        '302':
          description: Redirect to the provider.
        '404':
          description: That provider is not configured.
      security: []
  /v1/auth/oauth/{provider}/callback:
    get:
      summary: Finish a Google or GitHub sign-in
      description: Where the provider sends the person back. Only an address the provider has verified is accepted; it lands in the same account an emailed code for that address would. Always redirects to the sign-in page — with a session cookie on success, or `auth_error` on failure.
      tags:
      - Auth
      operationId: get_v1_auth_oauth__provider__callback
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
        description: '`google` or `github`.'
      responses:
        '302':
          description: Redirect to the sign-in page.
      security: []
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'A workspace API key, `cr_live_…`. Server-side only: it carries workspace authority and must never reach a browser.'
    session:
      type: apiKey
      in: cookie
      name: chatrail_session
      description: Dashboard session cookie. Set by `/v1/auth/verify`.