Basis Authentication

generated: '2026-08-13'
method: searched
source: >-
  Authentication section of the Basis Platform API description published by Basis
  at https://api.basis.net/swagger.json (fetched 2026-08-13, HTTP 200), plus the
  authorization-server discovery document at
  https://auth.basis.net/.well-known/openid-configuration (HTTP 200). Scheme names
  derived from openapi/basis-analytics-api-openapi.yml.
docs: https://api.basis.net/swagger.json
description: >-
  Every Basis Platform API endpoint requires authentication. Basis uses OAuth 2.0
  with an Auth0-hosted authorization server at https://auth.basis.net — explicitly
  NOT the API host. Access tokens are presented to https://api.basis.net as
  `Authorization: Bearer <access_token>`. Credentials are not self-serve: the API
  is available to Basis (formerly Centro) customers and integration partners, and
  organizations must obtain credentials from their Basis representative.
summary:
  types:
    - oauth2
    - http
  primary: oauth2
  self_serve_credentials: false
schemes:
  - name: OAuth2
    type: oauth2
    sources:
      - openapi/basis-analytics-api-openapi.yml
    note: >-
      Declared in the OpenAPI as a bare securityScheme with no `flows` object; the
      flows below are documented in prose in the same specification's
      info.description and confirmed against the authorization server's discovery
      document.
    flows:
      - grant: authorization_code
        authorization_endpoint: https://auth.basis.net/authorize
        token_endpoint: https://auth.basis.net/oauth/token
        audience: https://api.basis.net
        scopes: [openid, profile, email, offline_access]
        pkce: supported (code_challenge_methods_supported S256, plain)
        note: >-
          The only flow that returns a refresh token. Requires a redirect URI
          registered with Basis support.
      - grant: client_credentials
        token_endpoint: https://auth.basis.net/oauth/token
        audience: https://api.basis.net
        note: >-
          Machine-to-machine. The application must have an associated owner
          (agency) ID or the token endpoint returns 401. The resulting token
          covers all clients for that agency, so Basis recommends the
          authorization-code flow where restricted clients exist. User-scoped
          endpoints (e.g. GET /v1/me) return 404 under this flow because the token
          represents an organization, not a user.
        quota:
          tokens_per_hour: 10
          tokens_per_day: 25
          exhausted_status: 429
      - grant: refresh_token
        token_endpoint: https://auth.basis.net/oauth/token
        note: Returns a new access token and a new refresh token.
  - name: Bearer
    type: http
    scheme: bearer
    sources:
      - openapi/basis-analytics-api-openapi.yml
    header: 'Authorization: Bearer <access_token>'
    example: 'curl -X GET "https://api.basis.net/v1/agency" -H "Authorization: Bearer <access_token>"'
deprecated:
  - grant: password
    status: deprecated
    evidence: >-
      "The password grant flow has now been deprecated. Please update your
      applications to use one of the above two flows." — Basis Platform API
      description, https://api.basis.net/swagger.json
    note: >-
      The authorization server still advertises `password` and
      `http://auth0.com/oauth/grant-type/password-realm` in
      grant_types_supported, but Basis's own documentation deprecates it for this
      API.
token_endpoint_auth_methods_supported:
  - client_secret_basic
  - client_secret_post
  - private_key_jwt
  - none
id_token_signing_alg_values_supported: [HS256, RS256, PS256]
dpop_signing_alg_values_supported: [ES256]
unauthenticated_behavior:
  status: 401
  body: '{"message":"missing authorization header"}'
  evidence: probed https://api.basis.net/v1/me on 2026-08-13 (HTTP 401)
related:
  - scopes/basis-scopes.yml
  - well-known/basis-openid-configuration.json
  - conventions/basis-conventions.yml