Login with RDCPASS

Endpoints

Instead of building your own login form and calling KYC Validation yourself, redirect the citizen to RDCPASS. They approve your request on their own phone — a push notification, a review of exactly the KYC scopes you're asking for, and a face-recognition check, never a password — and RDCPASS redirects them back with proof of who they are: an id_token, signed and ready to verify, carrying the basic KYC claims and every additional KYC scope the citizen approved.

Register your redirect URIs first

Before any of this works, an Owner or Administrator of your organization must register the exact redirect_uri value(s) your application will use, from the console. /v1/oidc/authorize rejects any request whose redirect_uri isn't an exact, byte-for-byte match against one already on file — no wildcards, no partial matches. This is what stops a stolen client_id from being used to redirect a citizen's login to an attacker-controlled URL.

How it works

1. 1

   Redirect to the authorization endpoint — Send the citizen’s browser to /v1/oidc/authorize with a fresh PKCE challenge and state value.

2. 2

   Citizen approves on their phone — RDCPASS pushes a notification to their enrolled device. They review exactly the scopes you’re requesting and confirm with a face-recognition check — nothing is shared silently, and no password is ever involved.

3. 3

   RDCPASS redirects back to you — Your redirect_uri receives an authorization code (or an error) as a query parameter, plus your original state value unchanged.

4. 4

   Exchange the code for tokens — Your server calls /v1/oidc/token directly (never the browser) to trade the one-time code for an access token and id_token.

Step 1 — authorization request

Redirect the citizen’s browser to a URL shaped like this:

https://api.rdcpass.cd/v1/oidc/authorize
  ?response_type=code
  &client_id=app_8f2a1c0e9b
  &redirect_uri=https%3A%2F%2Fyourapp.example.com%2Fcallback
  &scope=openid%20profile%20rdcpass%3Akyc.addresses%20rdcpass%3Akyc.phone_numbers%20rdcpass%3Akyc.emails%20rdcpass%3Akyc.documents.primary
  &state=af0ifjsldkj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

Query parameters:

How citizens approve: push notification and face recognition

Everything below happens on RDCPASS’s own hosted page, reached by the Step 1 redirect — none of it is an API your application calls. It’s documented here so you can set the right expectations for your own users and support team.

1. 1

   The citizen identifies themselves on RDCPASS’s page — their registered phone number or national identity document number. This never passes through your application; RDCPASS’s hosted page is the only place it’s entered.

2. 2

   RDCPASS immediately pushes a notification to every device where the citizen has the RDCPASS app installed and enrolled. It names your application by its verified display name — resolved from your client_id, never something your request can set — and lists exactly the scopes you’re requesting, in plain language — no more, no less.

3. 3

   Opening the notification shows the same consent screen in full inside the app — every requested scope, with sensitive and biometric scopes flagged — and Continue and Deny. The citizen approves or denies the request as a whole.

4. 4

   Continue starts a face-recognition check, matched server-side against the citizen’s enrolled RDCPASS biometric record — the same enrollment used elsewhere on the platform, not just whatever unlocks their phone.

5. 5

   The citizen has 60 seconds total, starting from the Step 1 redirect, to complete all of the above. Declining, failing the face match, or simply not responding in time all end the same way — see access_denied below.

A citizen with no RDCPASS app installed, or no enrolled biometric, is guided to set both up on RDCPASS’s own page before they can continue — there is no password fallback.

Step 2 — the callback

On success, RDCPASS redirects to your redirect_uri with a code:

https://yourapp.example.com/callback
  ?code=auth_9f2ac3d0e1b74a2f9c7d5b3a1e6f8c0d
  &state=af0ifjsldkj

If the citizen declines, or something goes wrong before a code can be issued, you get an error on the same redirect_uri instead — never a code and an error together:

https://yourapp.example.com/callback
  ?error=access_denied
  &error_description=The citizen declined to authorize your application
  &state=af0ifjsldkj

See OAuth error codes below for every value error can take.

Step 3 — exchange the code for tokens

From your server (never from the browser — this call requires your application’s mTLS client certificate), exchange the code:

Example token exchange

curl https://api.rdcpass.cd/v1/oidc/token \
  -X POST \
  --cert your-app-client-cert.pem \
  --key your-app-client-key.pem \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=auth_9f2ac3d0e1b74a2f9c7d5b3a1e6f8c0d" \
  -d "redirect_uri=https://yourapp.example.com/callback" \
  -d "client_id=app_8f2a1c0e9b" \
  -d "code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

{
  "access_token": "rdcp_at_9f2ac3d0e1b74a2f8c0d5b3a1e6f8c0d",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5yZGNwYXNzLmNkIiwic3ViIjoiY2l0XzdmMWUyYTljNGIzZDhmNjAiLCJhdWQiOiJhcHBfOGYyYTFjMGU5YiIsImV4cCI6MTczNTY5MzIwMCwiaWF0IjoxNzM1Njg5NjAwfQ.signature",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile rdcpass:kyc.addresses rdcpass:kyc.phone_numbers rdcpass:kyc.emails rdcpass:kyc.documents.primary"
}

A successful exchange returns:

ID token claims

Decode and verify the id_token’s signature (see Verifying the id_token below) before trusting any claim inside it. Which claims appear depends on the scopes granted — this example was issued for "openid profile rdcpass:kyc.addresses rdcpass:kyc.phone_numbers rdcpass:kyc.emails rdcpass:kyc.documents.primary". File-bearing claims such as rdcpass:documents.primary are delivered by userinfo only (see below).

{
  "iss": "https://api.rdcpass.cd",
  "sub": "cit_7f1e2a9c4b3d8f60",
  "aud": "app_8f2a1c0e9b",
  "exp": 1735693200,
  "iat": 1735689600,
  "nonce": "n-0S6_WzA2Mj",
  "rdcpass_id": "COD-2103-0214-4937",
  "full_name": "Kabeya Mwamba Tshisekedi",
  "given_name": "Kabeya",
  "family_name": "Tshisekedi",
  "birthdate": "1988-04-12",
  "age": 38,
  "gender": "male",
  "nationality": "COD",
  "account_status": "active",
  "certified": true,
  "level_of_assurance": "LOA3",
  "account_created_at": "2025-03-14T09:22:41Z",
  "rdcpass:addresses": [
    {
      "province": "Kinshasa",
      "city": "Kinshasa",
      "commune": "Gombe",
      "quartier": "Batetela",
      "avenue": "Avenue du Commerce",
      "number": "12",
      "is_primary": true,
      "verified_at": "2025-03-14T09:40:12Z"
    }
  ],
  "rdcpass:phone_numbers": [
    { "number": "+243812345678", "operator": "Vodacom", "is_primary": true, "verified": true }
  ],
  "rdcpass:emails": [
    { "address": "kabeya.tshisekedi@example.cd", "is_primary": true, "verified": true }
  ]
}

Verifying the id_token

The id_token is a JWT signed with RS256. Fetch RDCPASS’s public keys from /v1/oidc/jwks.json — no authentication required — and verify the signature before trusting anything inside the token.

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "2026-08-rsa-1",
      "n": "sXchd3fN0Vy0zGsFdX1...",
      "e": "AQAB"
    }
  ]
}

1. Fetch and cache /v1/oidc/jwks.json (keys rotate infrequently; respect standard HTTP caching headers rather than fetching on every request).
2. Verify the signature using the key matching the token’s "kid" header.
3. Check iss equals "https://api.rdcpass.cd".
4. Check aud equals your own client_id.
5. Check exp hasn’t passed.
6. If you sent a nonce, check it matches.

Standard JWT/JOSE libraries in every language handle all of this — jose (Node.js/Python), golang-jwt (Go), nimbus-jose-jwt (Java), jsonwebtoken (Rust’s jsonwebtoken crate), firebase/php-jwt (PHP), and System.IdentityModel.Tokens.Jwt (C#) all support fetching a JWKS URL and verifying RS256 directly.

Reading the profile again — /v1/oidc/userinfo

Call this endpoint with the access token as a bearer credential to read the full set of claims for the granted scopes — including the file-bearing claims (documents, biometrics) that are never embedded in the id_token. Document images and biometric files are returned as signed_url file objects, valid for 5 minutes: fetch them server-side and never store the URL.

GET /v1/oidc/userinfo HTTP/1.1
Host: api.rdcpass.cd
Authorization: Bearer rdcp_at_9f2ac3d0e1b74a2f8c0d5b3a1e6f8c0d

{
  "sub": "cit_7f1e2a9c4b3d8f60",
  "rdcpass_id": "COD-2103-0214-4937",
  "full_name": "Kabeya Mwamba Tshisekedi",
  "given_name": "Kabeya",
  "family_name": "Tshisekedi",
  "birthdate": "1988-04-12",
  "age": 38,
  "gender": "male",
  "nationality": "COD",
  "account_status": "active",
  "certified": true,
  "level_of_assurance": "LOA3",
  "account_created_at": "2025-03-14T09:22:41Z",
  "rdcpass:addresses": [
    {
      "province": "Kinshasa",
      "city": "Kinshasa",
      "commune": "Gombe",
      "quartier": "Batetela",
      "avenue": "Avenue du Commerce",
      "number": "12",
      "is_primary": true,
      "verified_at": "2025-03-14T09:40:12Z"
    }
  ],
  "rdcpass:phone_numbers": [
    { "number": "+243812345678", "operator": "Vodacom", "is_primary": true, "verified": true }
  ],
  "rdcpass:emails": [
    { "address": "kabeya.tshisekedi@example.cd", "is_primary": true, "verified": true }
  ],
  "rdcpass:documents.primary": {
    "type": "passport",
    "number": "OB1234567",
    "issued_at": "2022-06-01",
    "expires_at": "2027-05-31",
    "issuing_authority": "Ministère des Affaires étrangères",
    "status": "valid",
    "image": {
      "content_type": "image/jpeg",
      "url": "https://files.rdcpass.cd/d/9f2c41e7ab03?sig=Q2hhbmdlTWU",
      "expires_at": "2026-09-26T10:20:02Z"
    }
  }
}

Scopes and claims

Login with RDCPASS uses the same KYC scopes as every other RDCPASS service. openid is always required; profile returns the basic KYC claims; each additional scope is requested as rdcpass:<scope> and returns one claim named after it. See KYC scopes & subscriptions for what each scope contains.

Credit-scoring consent — rdcpass:credit.score

Requesting rdcpass:credit.score asks the citizen to consent, on the same consent screen, to a credit score being computed about them. When approved, the id_token and userinfo carry a rdcpass:credit.consent claim; pass its value as the consent field of Credit Scoring. The consent is scoped to your application and expires at expires_at.

"rdcpass:credit.consent": {
  "method": "rdcpass_app",
  "consent_id": "cns_5e8a2d71c4",
  "expires_at": "2026-10-26T10:15:00Z"
}

OAuth error codes

These four endpoints use standard OAuth 2.0 error codes and shapes — NOT the error JSON body the rest of the API returns. An authorize-step error arrives as redirect query parameters (see Step 2 above); a token-step error arrives as a JSON body with the same field names, but returned with a 400 status instead of a redirect.

Rate limits

These endpoints are metered under the sso_login service, subject to whatever sandbox or production quota your application is on. See Rate limits & quotas for current limits. Every other error condition not covered above — malformed mTLS, quota, etc. — uses the standard error format described in Errors.