Amperity Authentication

generated: '2026-08-13'
method: searched
source: https://docs.amperity.com/api/authentication.html
docs: https://docs.amperity.com/api/authentication.html
summary:
  types: [oauth2, http]
  http_scheme: bearer
  bearer_format: JWT
  oauth2_flows: [clientCredentials, authorizationCode]
  surfaces: 2
  surfaces_note: >-
    Amperity runs TWO separate OAuth2 deployments with different flows, different token endpoints and
    different identity models. The REST APIs use client-credentials against a tenant token endpoint and
    authenticate a SYNTHETIC IDENTITY (an API key). The hosted MCP server uses authorization-code with
    PKCE against mcp.amperity.com and authenticates a REAL HUMAN USER, scoping every request to that
    user's identity, tenant and permissions. They are not interchangeable.
overview: >-
  Amperity APIs authenticate with a JWT bearer access token. An administrator creates an API key
  (a synthetic identity bound to the tenant) under Settings > Security > API keys, granting it the
  DataGrid Operator role. The API key's client_id/client_secret are exchanged for a short-lived
  access token via the OAuth2 client-credentials token endpoint. All API requests then send the
  token in the Authorization header, plus a tenant identifier header and a date-based api-version
  header.
schemes:
- name: OAuth2ClientCredentials
  type: oauth2
  flows:
  - flow: clientCredentials
    tokenUrl: https://{tenant}.amperity.com/api/v0/oauth2/token
    grant_type: client_credentials
    request_content_type: application/x-www-form-urlencoded
    request_params: [client_id, client_secret]
    token_response:
      access_token: string
      token_type: Bearer
      expires_in: 3600
    scopes: {}
  sources: [https://docs.amperity.com/api/authentication.html]
- name: BearerJWT
  type: http
  scheme: bearer
  bearerFormat: JWT
  applied_via: 'Authorization: Bearer ${access-token}'
  sources: [https://docs.amperity.com/api/authentication.html]
required_headers:
- name: Authorization
  value: 'Bearer ${access-token}'
  apis: [Amperity API, Profile API, Streaming API]
- name: amperity-tenant
  value: '{tenant-id}'
  apis: [Profile API]
- name: X-Amperity-Tenant
  value: '{tenant-name}'
  apis: [Amperity API, Streaming API]
- name: api-version
  value: 'YYYY-MM-DD (e.g. 2024-04-01 for Amperity API, 2025-07-31 for Profile API)'
  apis: [Amperity API, Profile API]
token_lifecycle:
  format: JWT
  expiry: 'expires_in seconds (default 3600); UI-generated tokens expire after a configured number of days'
  refresh: 'no refresh-grant flow; regenerate via client-credentials exchange or the UI'
  key_rotation: 'rotating an API key mints a new secret; previously issued tokens remain valid for 30 days (deposed state) before becoming invalid'
notes:
- API keys are managed under Settings > Security and require the API key administration policy.
- The Streaming API uses a self-managed Streaming Ingest JWT token generated in the UI.
mcp_oauth:
  surface: https://mcp.amperity.com
  method: probed
  source: well-known/amperity-oauth-authorization-server.json
  checked: '2026-08-13'
  type: oauth2
  flow: authorization_code
  pkce: S256
  issuer: https://mcp.amperity.com
  authorization_endpoint: https://mcp.amperity.com/authorize
  token_endpoint: https://mcp.amperity.com/oauth/token
  registration_endpoint: https://mcp.amperity.com/oauth/register
  response_types_supported: [code]
  grant_types_supported: [authorization_code]
  token_endpoint_auth_methods_supported: [none]
  bearer_methods_supported: [header]
  dynamic_client_registration: true
  published_client_id: nwbd0MGCyh1VysmYQM05UoDXIuVPdGEs
  published_client_id_note: >-
    Amperity publishes this public client id verbatim in its Claude setup documentation for use when
    adding the custom connector. It is a public client (token_endpoint_auth_methods_supported: [none]),
    not a secret.
  challenge:
    observed: 'HTTP 401 on POST tools/list'
    www_authenticate: 'Bearer resource_metadata="https://mcp.amperity.com/.well-known/oauth-protected-resource"'
    note: 'Full RFC 9728 protected-resource handshake - the 401 points a client at its own metadata.'
  scopes:
    published: []
    note: >-
      No scopes_supported is advertised in the authorization-server metadata and no scope reference
      page exists. Authorization is carried by the calling user's Amperity policies and by the
      per-session MCP safety mode, not by OAuth scopes. This is why no scopes/ artifact is emitted for
      Amperity - there is no scope surface to record.
  authorization_model:
    basis: 'The calling user''s Amperity identity, tenant access and policies.'
    session_guardrail: 'Per-session MCP safety mode (strict / confirm / unrestricted).'
    ref: mcp/amperity-mcp.yml