Ask Sage Authentication API

openapi: 3.2.0
info:
  title: Ask Sage User API — Full Response Reference Authentication…
  description: 'Ask Sage User API for account management, organization administration, billing, and platform configuration.


    ## Base URL

    `https://api.asksage.ai/user`


    ## Authentication

    Most endpoints require a valid JWT token sent in the `x-access-tokens` HTTP header. Secured endpoints show a padlock in Swagger UI / Redoc — click **Authorize** and paste your token once to apply it to every request.


    Get a token from `/get-token-with-api-key` (your email + 64-character API key), then send it on each call:


    `x-access-tokens: `


    **No token required:** `/get-token-with-api-key`, `/register`, `/verify-email`, `/lost-pass`, and `GET /get-headers`.


    Beyond a valid token, admin (`admin-*`) and superadmin (`superadmin-*`) endpoints require the caller to hold the matching role, and many identify the target user via an `email` field in the request body.

    ## Key Features

    - **User Management** — Profile updates, API key management, login history

    - **Chat Sessions** — Create, retrieve, and manage conversation history

    - **Dataset Management** — Create datasets, manage permissions and assignments

    - **Workbooks** — Organize research with sources and memos

    - **Organization Admin** — User management, token allocation, usage reporting

    - **Superadmin** — Platform-wide administration and analytics'
  version: '2.0'
  contact:
    name: Support
    email: support@asksage.ai
    url: https://asksage.ai
servers:
- url: '{baseUrl}/user'
  description: Ask Sage User API
  variables:
    baseUrl:
      default: https://api.asksage.ai
      description: API base URL. Use https://api.asksage.ai for production, or your self-hosted instance URL.
security:
- ApiKeyAuth: []
tags:
- name: Authentication
  description: User authentication and authorization
paths:
  /get-token-with-api-key:
    post:
      summary: Get token using API key
      tags:
      - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - api_key
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                  description: Email address of the account the API key belongs to; normalized to lowercase before lookup and must match the key's owner.
                api_key:
                  type: string
                  minLength: 64
                  maxLength: 64
                  description: The account's 64-character API key; exchanged for a bearer access token and must not be revoked.
      responses:
        '200':
          description: Access token issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      access_token:
                        type: string
                        description: JWT access token
                  status:
                    type: string
                    example: '200'
        '400':
          description: Missing required fields, invalid email, key does not exist or revoked, login failed, account disabled, email unverified, non-paid account, or internal error. Envelope {'response':<message>,'status':400 or '400'}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                response: Bad request
                status: 400
      operationId: postGetTokenWithApiKey
      x-operation-id-source: derived
components:
  schemas:
    ErrorResponse:
      type: object
      description: Standard Ask Sage error envelope.
      properties:
        response:
          type: string
          description: Human-readable error message.
        status:
          type: integer
          example: 400
          description: HTTP-style status code (usually an integer; some endpoints return it as a numeric string).
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-access-tokens
      description: JWT authentication token. Obtain a token by calling `/get-token-with-api-key` with your email and 64-character API key. Some admin and superadmin endpoints also require an email address in the request body to identify the target user.
x-provenance:
  method: harvested
  publisher: Ask Sage
  source: https://docs.asksage.ai/api-docs/specs/user-api-spec.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)