openapi: 3.1.0
info:
  title: Datablist Authentication API
  version: 1.0.0
  description: Exchange a Personal API Key for an account access token.
servers:
  - url: https://api.datablist.com
security: []
tags:
  - name: Authentication
    description: Get an access token to authenticate Datablist API requests.
paths:
  /v1/account/token:
    post:
      operationId: getAccessToken
      summary: Get an access token
      tags: [Authentication]
      description: |
        Exchange your Personal API Key for an account-bound access token. Create
        a key on the [API page in your Datablist account](https://app.datablist.com/account/api).

        This endpoint does not require a bearer token. Send JSON with your
        Personal API Key in the `apiKey` field. No path or query parameters are
        required. The maximum request body size is 4 KiB.

        Use the returned `access_token` as `Authorization: Bearer ACCESS_TOKEN`
        for datastore, enrichment, source, credits, and MCP requests. The token
        expires after 24 hours; exchange your key again after expiration.
        Deleting a key prevents future exchanges but does not revoke tokens
        already issued. Keep both credentials out of URLs and logs.

        To authenticate requests in this documentation, open **Try it** on an
        endpoint and click **Connect**. The documentation handles this exchange
        there and keeps your credentials in memory. See the
        [authentication guide](/docs/enrichments/authentication) for details.
      requestBody:
        required: true
        description: Your Personal API Key, sent as JSON.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessTokenRequest'
            example:
              apiKey: YOUR_PERSONAL_API_KEY
      responses:
        '200':
          description: Access token and account information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenResponse'
              example:
                access_token: ACCESS_TOKEN
                token_type: Bearer
                expires_in: 86400
                expires_at: 1791712800
                account_id: account_example
                user_id: user_example
                plan: starter
                scope: [admin]
        '400':
          description: Missing or malformed Personal API Key, or invalid JSON body.
        '401':
          description: The Personal API Key is invalid or has been deleted.
        '413':
          description: The request body exceeds the 4 KiB limit.
components:
  schemas:
    AccessTokenRequest:
      type: object
      required: [apiKey]
      properties:
        apiKey:
          type: string
          minLength: 1
          description: Personal API Key created in your Datablist account. Do not send an access token here.
    AccessTokenResponse:
      type: object
      required: [access_token, token_type, expires_in, expires_at, account_id, user_id, plan, scope]
      properties:
        access_token:
          type: string
          description: JWT access token. Send it in the Authorization header using the Bearer format.
        token_type:
          type: string
          enum: [Bearer]
          description: Authentication scheme to use with the access token.
        expires_in:
          type: integer
          description: Token lifetime in seconds (86400 seconds, or 24 hours).
        expires_at:
          type: integer
          description: Expiration time as a Unix timestamp in seconds.
        account_id:
          type: string
          description: Datablist account identified by the Personal API Key.
        user_id:
          type: string
          description: User who created the Personal API Key.
        plan:
          type: string
          description: Account plan when the token was issued.
        scope:
          type: array
          items:
            type: string
          description: Account permissions granted to the token. Personal API Keys issue admin scope.