Akkio Authentication

generated: '2026-08-13'
method: searched
source: https://docs.akkio.com/akkio-docs/concepts/authentication
docs: https://docs.akkio.com/akkio-docs/concepts/authentication
summary:
  types: [apiKey]
  api_key_in: [header, query, body]
  oauth2_flows: []
  notes: >-
    Akkio authenticates every request with a single team-scoped API key, issued
    and rotated from the Team Settings page of the app. There are THREE distinct
    placements in production, and which one applies depends on which of Akkio's
    two API generations you are calling. The current /api/v1 public beta API
    requires the key in an X-API-Key HEADER on every route except the two
    "API Specification" routes (/api/v1/api.yaml and /api/v1/docs), which are
    anonymous — that rule is stated in the published spec's own info.description.
    The legacy /v1 datasets/models API instead takes the key as an `api_key`
    QUERY parameter on GET and as an `api_key` JSON BODY field on POST/DELETE.
    There is no OAuth 2.0 or OIDC surface for API consumers, so no scopes/
    artifact is produced. Neither published OpenAPI document declares a
    securitySchemes block at all, so a generated client will not wire auth
    automatically — the requirement exists only in prose and in info.description.
schemes:
- name: X-API-Key
  type: apiKey
  in: header
  parameter: X-API-Key
  applies_to: /api/v1 (Akkio Public API, beta)
  declared_in_spec: false
  sources:
  - https://docs.akkio.com/akkio-docs/concepts/authentication
  - openapi/_original/akkio-public-api-openapi.yaml
  evidence: >-
    'All routes but those marked "API Specification" require the X-API-Key header
    to be set to a valid API key.' — info.description of
    https://api.akkio.com/api/v1/api.yaml, fetched 2026-08-13.
- name: apiKeyQuery
  type: apiKey
  in: query
  parameter: api_key
  applies_to: legacy /v1 GET (datasets, models)
  declared_in_spec: true
  sources:
  - openapi/_original/akkio-api-openapi.yml
  - https://docs.akkio.com/akkio-docs/endpoints-and-schemas/endpoints/datasets
- name: apiKeyBody
  type: apiKey
  in: body
  parameter: api_key
  applies_to: legacy /v1 POST and DELETE (datasets, models)
  declared_in_spec: false
  sources:
  - https://docs.akkio.com/akkio-docs/endpoints-and-schemas/endpoints/models
  - https://github.com/akkio-inc/akkio-python
anonymous_routes:
- path: /api/v1/api.yaml
  note: Returns the public OpenAPI 3.1.0 YAML document; verified anonymous 200 on 2026-08-13.
- path: /api/v1/docs
  note: Swagger UI for the public API; verified anonymous 200 on 2026-08-13.
- path: /openapi.json
  note: >-
    The full FastAPI application schema is also served anonymously at the API
    host root; verified 200 on 2026-08-13. Not documented as a public route.
- path: /version
  note: Returns the build sha as text/plain; verified anonymous 200 on 2026-08-13.
- path: /health
  note: Verified anonymous 200 on 2026-08-13.
key_management:
  issue_url: https://app.akkio.com/team-settings
  scope: team / organization
  rotation: Self-service from Team Settings; no documented rotation policy or expiry.
  note: >-
    Authorization is organization-scoped: a 403 means the organization behind the
    key lacks access to the resource, per the authentication docs. There are no
    per-key scopes or permissions to narrow a key.
failure_semantics:
  '401': Missing, incorrect, or whitespace-padded X-API-Key.
  '403': The key's organization does not have access to the requested resource.
  note: See errors/akkio-problem-types.yml.
gaps:
- Neither published OpenAPI document declares components.securitySchemes.
- No OAuth 2.0 / OIDC option for API consumers; no per-key scopes.
- Three different key placements across two API generations, none machine-declared.
cross_links:
  conventions: conventions/akkio-conventions.yml
  errors: errors/akkio-problem-types.yml