Capsule Authentication

generated: '2026-09-05'
method: searched
source: https://developer.capsulecrm.com/v2/overview/authentication
docs: https://developer.capsulecrm.com/v2/overview/authentication
discovery:
  openid_configuration: https://api.capsulecrm.com/.well-known/openid-configuration
  oauth_authorization_server: https://api.capsulecrm.com/.well-known/oauth-authorization-server
  jwks_uri: https://api.capsulecrm.com/.well-known/jwks.json
  status: 200
  probed: '2026-09-05'
  saved: well-known/
description: >-
  Capsule authenticates every v2 REST request with a Bearer token in the
  Authorization header. Two token kinds exist: a personal access token minted
  inside a Capsule account, and an OAuth 2.0 authorization-code access token
  for multi-tenant applications. Upgraded from the 2026-07-11 derived profile,
  which recorded only the generic bearerAuth scheme from the OpenAPI.
summary:
  types:
  - http
  - oauth2
  - openIdConnect
schemes:
- name: bearerAuth
  type: http
  scheme: bearer
  in: header
  header: Authorization
  format: 'Authorization: Bearer {token}'
  description: >-
    Personal access token, generated at My Preferences > API Authentication
    Tokens inside a Capsule account. Suited to one-off integrations and
    testing. A token can be minted read-only ("Read information from your
    Capsule account"), which is what the Capsule MCP server asks for.
  sources:
  - https://developer.capsulecrm.com/v2/overview/authentication
- name: oauth2
  type: oauth2
  flow: authorizationCode
  pkce: true
  pkce_methods:
  - plain
  - S256
  authorizationUrl: https://api.capsulecrm.com/oauth/authorise
  tokenUrl: https://api.capsulecrm.com/oauth/token
  revocationUrl: https://api.capsulecrm.com/oauth/revoke
  revocation_note: >-
    The discovery document gives revocation_endpoint as
    https://api.capsulecrm.com/oauth/revoke; the authentication docs page
    writes it as .../oauth/token/revoke. Both are Capsule's own published
    values and they disagree - recorded as found, not reconciled.
  grant_types:
  - authorization_code
  - refresh_token
  token_endpoint_auth_methods:
  - client_secret_basic
  - client_secret_post
  scopes:
    see: scopes/capsule-scopes.yml
  access_token_ttl_seconds: 604799
  access_token_ttl_note: ~7 days, stated verbatim in the docs.
  refresh_tokens: true
  refresh_token_rotation: >-
    "Refresh tokens may be rotated; always store the most recent version."
  sources:
  - https://developer.capsulecrm.com/v2/overview/authentication
  - https://api.capsulecrm.com/.well-known/oauth-authorization-server
- name: openIdConnect
  type: openIdConnect
  openIdConnectUrl: https://api.capsulecrm.com/.well-known/openid-configuration
  issuer: https://api.capsulecrm.com
  userinfo_endpoint: https://api.capsulecrm.com/oauth/userinfo
  id_token_signing_alg_values_supported:
  - RS256
  claims_supported:
  - name
  - email
  - tenant
  - family_name
  - locale
  - iat
  - sub
  - updated_at
  - given_name
  - iss
  - exp
  - subdomain
  description: >-
    Capsule is a full OpenID Provider: the openid-configuration document is
    served, a JWKS is published, and openid/profile/email are among the
    supported scopes. This is not documented on the authentication docs page
    - it was found by probing /.well-known/ on the API host.
  sources:
  - https://api.capsulecrm.com/.well-known/openid-configuration
errors:
- {status: 401, meaning: invalid or expired token, header: WWW-Authenticate}
- {status: 403, meaning: valid token without the required scope, header: WWW-Authenticate}
mtls: false
api_key_query_param: false
maintainers:
- FN: Kin Lane
  email: kin@apievangelist.com