Aduna Authentication

generated: '2026-07-25'
method: searched
source: https://github.com/adunaglobal/nv2-asp-server-java-aduna-sdk
docs: https://docs.adunaglobal.com/how-to-enable-an-api/number-verification-api-v-2.1-landing-page
docs_gated: true
note: >-
  Aduna publishes no OpenAPI, so this profile is read verbatim from Aduna's own source-available
  Java SDK (Feign clients, configuration classes and README) rather than derived from a spec. The
  reference documentation exists but every path on docs.adunaglobal.com redirects to an Auth0 login
  wall, so the authoritative public evidence is the SDK source.
summary:
  types: [oauth2, openIdConnect, http]
  oauth2_flows: [authorizationCode, urn:ietf:params:oauth:grant-type:jwt-bearer, ciba]
  api_key_in: []
  bearer_token: true
  mutual_tls: false
  self_service: false
  onboarding: >-
    Client ID and client secret are issued per ASP application during a manual onboarding
    conversation. The SDK README states: "Contact Aduna Global for the onboarding procedure of an
    ASP Application." Redirect URLs must be registered with Aduna at onboarding and are validated
    by the Aduna platform on every authorization-code request.
schemes:
- name: network-based authorization
  type: oauth2
  flow: authorizationCode
  description: >-
    The device follows an Aduna-supplied invocation URL; the request results in a series of HTTP 302
    responses until a final 200 carrying the verification result. State and a pre-registered
    redirect URL are required; when they are omitted no network-based option is returned by
    /auth/auth-info.
  acquisition_mode: AUTHORIZATION_CODE
  source: https://github.com/adunaglobal/nv2-asp-server-java-aduna-sdk#sdk-number-verification-overview
- name: SIM-based authorization (JWT-Bearer)
  type: oauth2
  flow: urn:ietf:params:oauth:grant-type:jwt-bearer
  recommended: true
  description: >-
    RFC 7523 JWT-Bearer assertion flow. The ASP backend signs assertions with keys it manages and
    publishes; Aduna fetches the public keys from a single ASP-hosted JWKS URL supplied at
    onboarding. The SDK rotates signing keys on a configurable interval (default P90D, requested
    key TTL P91D) via the JwtBearerTokenKeyManager / JwtBearerTokenKeyRotator interfaces.
  acquisition_mode: JWT_BEARER_TOKEN
  integrator_requirements:
  - /.well-known/openid-configuration on the ASP backend exposing issuer, jwks_uri and subject_types_supported
  - /jwks on the ASP backend returning every public key used to sign assertions, across all instances
- name: SIM-based authorization (CIBA)
  type: oauth2
  flow: ciba
  description: >-
    OpenID Connect Client-Initiated Backchannel Authentication. POST /auth/bc-authorize returns a
    CibaResponse carrying auth_req_id, expires_in and a polling interval; the token is then
    collected from POST /auth/token.
  acquisition_mode: CIBA
- name: bearer access token
  type: http
  scheme: bearer
  description: >-
    All CAMARA resource calls carry Authorization: Bearer <access token> obtained from
    POST /auth/token. Tokens are returned with type and expires_in.
endpoints:
- method: POST
  path: /auth/auth-info
  purpose: >-
    Discover the authorization options available for a phone number or PLMN ID. Returns
    networkBasedAuthZData (an invocation URL) and/or simBasedAuthZData (iOS App Clip URL, Android
    app URL, app-info JWT and callback query parameter names).
  request_fields: [phoneNumber, plmnId, scopes, appId, appName, appCallbackUrl, nonce, vpRequest, state, redirectUrl]
  query_parameters: [lang]
- method: POST
  path: /auth/bc-authorize
  purpose: CIBA backchannel authentication request.
  content_type: application/x-www-form-urlencoded
- method: POST
  path: /auth/token
  purpose: Token endpoint for the authorization-code, JWT-Bearer and CIBA flows.
  content_type: application/x-www-form-urlencoded
base_url:
  published: false
  note: >-
    Both Feign clients bind to the injected configuration property
    ${com.adunaglobal.sdk.backend.connection.baseURL}. The host is supplied to a partner at
    onboarding; Aduna publishes no production base URL, so none is asserted here.
headers:
- name: Authorization
  required: true
  note: Client credentials on the /auth endpoints; Bearer access token on the CAMARA endpoints.
- name: X-Correlator
  required: true
  note: Random UUID generated per request by the SDK; carried on both auth and resource calls.
aduna_authorization_api_version: v1.4.0
portal_identity_provider:
  issuer: https://prod-aduna-global.us.auth0.com/
  well_known: https://prod-aduna-global.us.auth0.com/.well-known/openid-configuration
  status: 200
  artifact: well-known/aduna-portal-auth0-openid-configuration.json
  note: >-
    Auth0 tenant guarding the Aduna developer portal and documentation — NOT the network-API
    authorization server. Advertises authorization_code, device_authorization, userinfo, revocation
    and dynamic client registration, S256 PKCE, and client_secret_basic / client_secret_post /
    private_key_jwt / none client authentication. Its scopes_supported are stock Auth0 OIDC profile
    claims, not CAMARA scopes.
related:
  scopes: scopes/aduna-scopes.yml
  conventions: conventions/aduna-conventions.yml
  errors: errors/aduna-problem-types.yml