Authentication & Authorization

Every call to the SEP CAMARA APIs requires an OAuth 2.0 access token. Getting that token involves two steps:

Client Authentication — prove who your application is (client secret or private key JWT)

Grant Type — determine how you identify the subscriber (JWT Bearer, CIBA, Authorization Code, or Client Credentials)

1. Client Authentication Methods

Your application must authenticate itself when calling the token endpoint. Two methods are supported.

Option A — Client Secret

A shared secret issued by the platform when you create a TMF Application. Simpler to set up but the secret must be kept secure and never exposed in client-side code.

How to get it

During the TMF931 onboarding flow, create an Application via the TMF Integration page or API. The platform returns a clientSecret (also visible as "Generated Client Secret" in the MBAPI TMF Integration page). Store it securely — it is only shown once.

How to use it in a token request

Include client_id and client_secret as form parameters:

POST https://stg.api.telekom.com/token Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer &assertion=<signed_subscriber_jwt> &client_id=<your_client_id> &client_secret=<your_client_secret>

Option B — Private Key JWT (Asymmetric / PRIVATE_KEY_JWT)

You sign a short-lived client assertion JWT with your own private key. The token server verifies it using the public key from your registered JWKS endpoint. No secret is transmitted — more secure and recommended for production.

Setup steps

Generate an RSA key pair (2048+ bit) or EC key pair (P-256 / ES256)

Host your public key as a JWKS JSON endpoint accessible over HTTPS, e.g. https://yourdomain.com/.well-known/jwks.json

Send the JWKS URI to the DT MACE team for whitelisting on the token server — this is required before private key JWT auth will work

Client assertion JWT structure

Build and sign this JWT with your private key:

// Header { "alg": "RS256", // or ES256 for EC keys "kid": "<your_key_id>" // must match a kid in your JWKS } // Payload { "iss": "<your_client_id>", "sub": "<your_client_id>", // same as iss for client assertion "aud": "https://stg.api.telekom.com/token", "iat": 1720000000, "exp": 1720000300, // max 5 minutes "jti": "<unique_uuid>" }

Token request with private key JWT

2. Grant Types

The grant type determines how the subscriber identity is proven. Choose the grant type based on the API you are calling.

JWT Bearer
Most common

What: Your application signs a JWT assertion that identifies the subscriber (phone number). No user interaction is needed — fully machine-to-machine.

When to use: KYC, Sim Swap, Location Retrieval, Number Recycling, QoD, NV2, and most other CAMARA APIs.

Flow: Sign a JWT with the subscriber's phone number as sub → exchange at /token → use returned access_token to call the API.

JWT bearer assertion payload

{ "iss": "<your_client_id>", "sub": "tel:+491701234567", // subscriber phone in E.164, prefixed with "tel:" "aud": "https://stg.api.telekom.com/token", "iat": 1720000000, "exp": 1720000300, "jti": "<unique_uuid>", "scope": "sim-swap:check dpv:FraudPreventionAndDetection" }

Token request

POST https://stg.api.telekom.com/token Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer &assertion=<signed_jwt_above> &client_id=<your_client_id> &client_secret=<your_client_secret>

NV2 special case: For Number Verification v2.1, the sub is not a phone number but an operator token obtained via the TS.43 Digital Credentials flow: sub = "operatortoken:<operator_token>". The operator token is retrieved from the network via the Android Digital Credentials API and the DCQL aggregator.

CIBA — Client Initiated Backchannel Authentication

What: Triggers a network-side authentication challenge to the subscriber's SIM. The client polls until authorization is granted. No browser redirect needed.

When to use: Location Verification v2 (Germany), Device Roaming Status (Germany production).

Flow: POST to /bc-authorize with the subscriber hint → receive auth_req_id → poll /token every few seconds until the network grants authorization.

Step 1 — Backchannel authorization request

POST https://stg.api.telekom.com/bc-authorize Content-Type: application/x-www-form-urlencoded scope=openid location-verification:verify dpv:FraudPreventionAndDetection &login_hint=tel:+491701234567 &client_id=<your_client_id> &client_secret=<your_client_secret> // Response: { "auth_req_id": "abc123", "expires_in": 120, "interval": 5 }

Step 2 — Poll token endpoint every interval seconds

POST https://stg.api.telekom.com/token Content-Type: application/x-www-form-urlencoded grant_type=urn:openid:params:grant-type:ciba &auth_req_id=abc123 &client_id=<your_client_id> &client_secret=<your_client_secret> // While pending: HTTP 400 { "error": "authorization_pending" } // When granted: HTTP 200 { "access_token": "...", ... }

Authorization Code

What: The subscriber authorizes via a browser redirect. The network issues an authorization code at the redirect URI which is exchanged for a token. For network-based flows (on cellular), this can happen silently without user interaction.

When to use: Number Verification v1, QoD (network-based on cellular).

Flow: Redirect user to /authorize → subscriber authorizes (silently on-net) → network redirects back with code → exchange code for token at /token.

Step 1 — Build the authorization URL and redirect

GET https://stg.api.telekom.com/authorize ?response_type=code &client_id=<your_client_id> &redirect_uri=https://yourapp.com/callback &scope=openid number-verification:verify dpv:FraudPreventionAndDetection &state=<random_opaque_value> &nonce=<random_nonce>

Step 2 — Network redirects back with code

GET https://yourapp.com/callback ?code=<authorization_code> &state=<same_state_value>

Step 3 — Exchange code for token

POST https://stg.api.telekom.com/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code=<authorization_code> &redirect_uri=https://yourapp.com/callback &client_id=<your_client_id> &client_secret=<your_client_secret>

state parameter: The state value is returned unchanged in the redirect. Use it to carry context (e.g. which API you are testing, the environment, the subscriber phone) — up to ~2000 chars. Always verify it on return to prevent CSRF.

nonce parameter: Optional. The nonce is embedded inside the returned id_token JWT claims — useful for replay attack prevention. It does not appear in the redirect URL.

Network-based (silent) auth: When the user's device is on mobile data (not WiFi), the /authorize request is routed through the operator's network which identifies the SIM automatically. The redirect happens without any user interaction — the authorization code arrives immediately at your redirect_uri.

Authorization codes are single-use. Exchange the code for a token immediately — codes expire quickly (typically 60–120 seconds) and cannot be reused.

Client Credentials

What: Pure machine-to-machine. The token is scoped to the application itself — no subscriber identity.

When to use: Health check endpoints, NV2 health, some admin flows where no subscriber context is needed.