Cardtonic Authentication

specification: API Commons Authentication
specificationVersion: '0.1'
provider: Cardtonic
providerId: cardtonic
generated: '2026-09-05'
method: searched
source: https://docs.cardtonic.com - the Auth and User operation pages of Cardtonic's published API documentation
modified: '2026-09-05'
description: >-
  The Cardtonic Business API publishes no OpenAPI securitySchemes (components.securitySchemes is
  empty and every operation carries security: []), so this profile is read from the documented
  operations themselves rather than derived from the spec. Access is a two-stage model: a business
  user signs up and logs in to obtain a session token, then mints a long-lived API key through
  POST /users/generate-key. Every documented request additionally requires an X-Tonic-Env
  environment-selector header.
docs:
  - https://docs.cardtonic.com
  - https://cardtonic.com/developer
schemes:
  - id: tonic-env-header
    type: apiKey
    in: header
    name: X-Tonic-Env
    required: true
    description: >-
      Environment selector, required on all 14 documented operations. The only value published in
      Cardtonic's own examples is "development". This is a routing header, not a credential.
    evidence: 'parameters[] on every operation in openapi/cardtonic-openapi.yml'
    source: https://docs.cardtonic.com/sign-up-business-user-11716510e0.md
  - id: business-session-token
    type: http
    scheme: bearer
    description: >-
      POST /auth/login/business exchanges an email + password for a session token. Cardtonic does
      not document the header the token is presented in; the login response body carries a "token"
      field. Email verification is enforced before login succeeds - an unverified account returns
      403 "you're yet to verify your email".
    operations:
      - loginBusiness
      - verifyEmail
      - resendEmailVerification
      - forgotPassword
      - resetPassword
    evidence: 'responses of loginBusiness / verifyEmail in openapi/cardtonic-openapi.yml'
    source: https://docs.cardtonic.com/login-business-11716513e0.md
    gap: >-
      The presentation header (Authorization: Bearer vs a custom header) is not published. An
      integrator cannot construct an authenticated call from the documentation alone.
  - id: cardtonic-api-key
    type: apiKey
    description: >-
      POST /users/generate-key issues a private API key; GET /users/show-api-key returns the
      current one. Cardtonic's own response example shows the key carries a "PRIV_" prefix followed
      by 64 hex characters. The transport header for the key is not documented.
    operations:
      - generateApiKey
      - fetchApiKey
    key_prefix: PRIV_
    evidence: 'data.apiKey in the 200 response of generateApiKey'
    source: https://docs.cardtonic.com/generate-api-key-11716518e0.md
    gap: >-
      No securityScheme, no header name, no rotation or revocation operation is published.
mfa:
  supported: true
  description: >-
    Account-level two-factor authentication is togglable through POST /users/enable-2fa and
    POST /users/disable-2fa. Neither the factor type (TOTP, SMS, email) nor the challenge/verify
    step is documented.
  operations:
    - enable2fa
    - disable2fa
identity_verification:
  description: >-
    Business accounts are KYC-gated. POST /users/kyc/verify-bvn submits a Nigerian Bank Verification
    Number; POST /users/kyc/verify-kyc submits corporate documents and shareholder identity records
    (firstName, lastName, email, phoneNumber, id) with document URLs previously obtained from
    PUT /users/upload.
  operations:
    - addBvn
    - verifyKyc
    - uploadFile
  jurisdiction: Nigeria (BVN is a Central Bank of Nigeria identifier)
oauth2: false
openid_connect: false
mutual_tls: false
notes: >-
  /.well-known/openid-configuration and /.well-known/oauth-authorization-server return 404 on every
  Cardtonic host (see well-known/cardtonic-well-known.yml). There is no OAuth surface to describe.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com