Alphaai Authentication

generated: '2026-08-11'
method: searched
source: openapi/alphaai-rest-api-openapi.yml
docs: https://alphai.io/developers
description: >-
  Two authentication surfaces on two hosts. The REST API takes a single static
  bearer API key with a recognisable `ak_live_` prefix. The MCP server accepts
  either the SAME key as a bearer token or a full OAuth 2.1 authorization-code
  flow with PKCE and RFC 7591 dynamic client registration — the dual path is
  deliberate, so browserless agents (n8n, cron, CI) are not locked out of MCP.

summary:
  types: [http, oauth2]
  api_key_in: [header]
  oauth2_flows: [authorizationCode]

schemes:
  - name: apiKey
    type: http
    scheme: bearer
    bearerFormat: ak_live_*
    in: header
    header: Authorization
    applies_to: https://api.alphai.io
    description: |-
      Token of the form `ak_live_<random>`. Issued from
      `/account/api-keys` on the website. Send as `Authorization: Bearer …`.
    sources:
      - openapi/alphaai-rest-api-openapi.yml
    required_on: every request (global security requirement in the spec)
    key_management:
      issue_url: https://alphai.io/account/api-keys
      credit_card_required: false
      keys_per_account: {Free: 1, Basic: 1, Pro: 5}
      rotation: Keys can be revoked from the dashboard; a revoked key returns 401 "Invalid or revoked API key."
    constraints:
      - Header only. The docs state explicitly that keys never go in a query parameter.
      - >-
        Send API traffic to api.alphai.io directly rather than through the
        website host — the provider notes the API host has no browser-oriented
        bot filtering.

  - name: MCP OAuth 2.1
    type: oauth2
    applies_to: https://mcp.alphai.io/mcp
    flows:
      - flow: authorizationCode
        authorizationUrl: https://mcp.alphai.io/oauth/authorize
        tokenUrl: https://mcp.alphai.io/oauth/token
        refreshUrl: https://mcp.alphai.io/oauth/token
        scopes: [tools.read, tools.bulk]
        pkce: S256
    dynamic_client_registration: true
    registration_endpoint: https://mcp.alphai.io/oauth/register
    sources:
      - well-known/alphaai-oauth-authorization-server.json
      - well-known/alphaai-oauth-protected-resource.json
    detail: scopes/alphaai-scopes.yml

  - name: MCP bearer (API key)
    type: http
    scheme: bearer
    bearerFormat: ak_live_*
    applies_to: https://mcp.alphai.io/mcp
    description: >-
      The REST key used as an MCP bearer token, for clients with no browser to
      run the OAuth flow. Documented at https://alphai.io/mcp.
    sources: [https://alphai.io/mcp]

failure_modes:
  - status: 401
    when: no Authorization header
    body: '{"detail": "API key required."}'
    observed: '2026-08-11'
  - status: 401
    when: malformed / revoked key
    body: '{"message":"Invalid or revoked API key.","extra":{}}'
    headers: 'WWW-Authenticate: Bearer'
    observed: '2026-08-11'
  - status: 401
    when: MCP request with no token
    body_fields: [error, reason, how_to_connect]
    headers: 'WWW-Authenticate: Bearer realm="alphai-mcp", resource_metadata="https://mcp.alphai.io/.well-known/oauth-protected-resource/mcp"'
    observed: '2026-08-11'
    note: >-
      A model 401 — it names the resource metadata document AND carries a plain
      how_to_connect string telling the caller where to create a key.

notes:
  - >-
    The two 401 envelopes on the REST API are inconsistent: a missing key returns
    a `detail` field, an invalid key returns `message` + `extra`. Both shapes are
    permitted by the spec's Error schema, but an agent has to handle both.
  - >-
    There is no per-key scoping on REST. A key is a whole-account credential; the
    only differentiation is plan tier.