Dukumentiyada API

REST · OAUTH 2.1 · OIDC

API REFERENCE · OAUTH 2.1 · OIDC

Dukumentiyada JaalleID API.

Endpoint kasta wuxuu raacaa OAuth 2.1, OIDC Discovery, iyo W3C Verifiable Credentials. JSON kaliya. Bearer kaliya. PKCE waa lagama maarmaan.

Guud ahaan

URL-ka ASAASIGA AH

https://id.jaalle.com

AQOONSIGA

Codsiyada lagu hayo magaca isticmaalaha waxa lagu ogolaadaa bearer-token caadi ah. Codsiyada heer-sare waxay isticmaalaan DPoP-binding (RFC 9449) si saxiixyada loo xidho cinwaan-saxiixaha.

OAuth 2.1

PKCE S256 · DPoP

SD-JWT VC

OAuth 2.1 + OIDC

Khadadka OAuth 2.1 caadiga ah, oo lagu xoojiyay PKCE S256 lagama-maarmaan, FIDO2/WebAuthn-step-up, iyo SD-JWT VC issuance.

GET/api/oauth/authorizepublic

Bilow xidhiidh oggolaansho. U haga isticmaalaha halkan si ay ugu soo galaan JaalleID.

Parameters

Name	Type	Required	Description
`client_id`	`string`	required	Your OAuth client identifier.
`redirect_uri`	`string`	required	A redirect URI registered for this client.
`response_type`	`string`	required	Must be "code".
`scope`	`string`	required	Space-separated. e.g. "openid profile email kyc_status trust_score".
`code_challenge`	`string`	required	PKCE S256 challenge — base64url(SHA-256(verifier)).
`code_challenge_method`	`string`	required	Must be "S256". "plain" is rejected.
`state`	`string`	required	Opaque value bound to the user session for CSRF protection.
`prompt`	`string`	optional	"none" · "login" · "consent" · "select_account".

Response

HTTP

1HTTP 307 → ${redirect_uri}?code=AUTH_CODE&state=ORIGINAL_STATE

POST/api/oauth/tokenclient_credentials

Ku beddel code-ka aqoonsi tokens. PKCE verifier waa lagama maarmaan.

Request body

JSON

1{2  "grant_type": "authorization_code",3  "code": "AUTH_CODE",4  "redirect_uri": "https://app.example.so/callback",5  "client_id": "jid_your_client_id",6  "code_verifier": "ORIGINAL_PKCE_VERIFIER"7}

Response

JSON

1{2  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Im...",3  "token_type": "Bearer",4  "expires_in": 900,5  "refresh_token": "rft_dGhpcyBpcyBhIHJlZnJlc2g...",6  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Im...",7  "scope": "openid profile email kyc_status trust_score"8}

Errors

`invalid_grant`	`400`	Code or PKCE verifier mismatch / expired.
`invalid_client`	`401`	Client authentication failed.

GET/api/oauth/userinfobearer

Soo qaad xog-aqoonsigan la xaqiijiyay ee isticmaalaha hadda saxan.

Response

JSON

1{2  "sub": "550e8400-e29b-41d4-a716-446655440000",3  "jaalle_id": "JID-A3K7M9PQ-R2T4",4  "name": "Mohamed Hassan",5  "email": "mohamed@example.com",6  "email_verified": true,7  "phone": "+252615551234",8  "phone_verified": true,9  "kyc_tier": "VERIFIED",10  "trust_score": 78,11  "identity_level": 212}

POST/api/oauth/revokeclient_credentials

Revoke an access or refresh token (RFC 7009).

Request body

JSON

1{2  "token": "rft_dGhpcyBpcyBhIHJlZnJlc2g...",3  "token_type_hint": "refresh_token"4}

Response

HTTP

1HTTP 200 (no body)

POST/api/oauth/introspectclient_credentials

Introspect token state (RFC 7662).

Request body

JSON

1{ "token": "eyJhbGciOi..." }

Response

JSON

1{2  "active": true,3  "scope": "openid profile email",4  "client_id": "jid_your_client_id",5  "sub": "uuid",6  "exp": 17474000007}

DPoP iyo FIDO2

DPOP-BOUND TOKENS · RFC 9449

Markaad rabto in token ku xidho cinwaanka codsiga, ku dar madaxa DPoP. SDK-yada Jaalle waxay si toos ah u maamulaan saxiixyada.

HTTP

1POST /api/v1/wallet/transfer HTTP/1.12Host: id.jaalle.com3Authorization: DPoP eyJhbGciOiJSUzI1NiIsImtpZCI6...4DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2I...

FIDO2 · WEBAUTHN

Step-up authentication adigoo isticmaalaya passkey ama amniga furayaasha hardware.

POST/api/oauth/fido2/challengebearer

Generate a WebAuthn assertion challenge bound to the active session.

Response

JSON

1{2  "challenge": "base64url...",3  "timeout": 60000,4  "rpId": "id.jaalle.com",5  "allowCredentials": [6    { "id": "base64url...", "type": "public-key" }7  ]8}

Aqoonsiga

GET/api/v1/identitybearer

Fetch the current user's full sovereign identity record.

Response

JSON

1{2  "id": "uuid",3  "jaalleId": "JID-A3K7M9PQ-R2T4",4  "kycTier": "VERIFIED",5  "trustScore": 78,6  "identityLevel": 2,7  "fullName": "Mohamed Hassan",8  "dateOfBirth": "1991-04-12",9  "region": "Banaadir",10  "issuedAt": "2025-09-13T08:22:00Z"11}

GET/api/v1/identity/lookuppublic

Public minimal-claim lookup by JIN. Rate-limited.

Parameters

Name	Type	Required	Description
`jaalle_id`	`string`	required	The JIN to look up (JID-XXXXXXXX-XXXX format).

Response

JSON

1{2  "found": true,3  "display_name": "Mohamed H.",4  "verification_level": "L2",5  "trust_score": 786}

KYC

POST/api/v1/verifybearer

Submit a KYC document for verification. Returns immediately with PROCESSING state.

Request body

multipart/form-data

1FormData {2  type: "national_id" | "passport" | "driver_licence"3  file: <binary>4  selfie: <binary>  // optional, required for L3+5}

Response

JSON

1{2  "id": "uuid",3  "status": "PROCESSING",4  "expected_completion": "2026-05-15T12:04:00Z"5}

Verifiable Credentials

OID4VCI ku salaysan SD-JWT VC. 13 nooc oo caddayn ayaa la taageeraa.

POST/api/v1/credentials/offerbearer

Create a credential offer (pre-authorized code flow).

Request body

JSON

1{ "credential_type": "NationalIdentity" }

Response

JSON

1{2  "credential_offer": { "credential_issuer": "...", "credentials": [...] },3  "credential_offer_uri": "openid-credential-offer://...",4  "offer_id": "uuid"5}

POST/api/v1/credentials/issuebearer

Exchange pre-authorized code for an SD-JWT VC.

Request body

JSON

1{2  "grant_type": "urn:ietf:params:oauth:grant-type:pre-authorized_code",3  "pre-authorized_code": "...",4  "proof": { "proof_type": "jwt", "jwt": "..." }5}

Response

JSON

1{2  "credential": "eyJ...~disc1~disc2~",3  "format": "vc+sd-jwt",4  "c_nonce": "..."5}

Webhooks

14 dhacdo

identity.createdidentity.updatedidentity.suspendedkyc.approvedkyc.rejectedkyc.document_submittedcredential.issuedcredential.revokedcredential.verifieddevice.registereddevice.revokedvouch.grantedvouch.revokedcivil_event.registered

Saxiixa Webhook · HMAC-SHA256

Webhook kasta wuxuu la socdaa madaxa X-JaalleID-Signature oo ah HMAC-SHA256 hex-encoded.

TypeScript

1import crypto from 'crypto'2 3export function verify(raw: string, signature: string, secret: string) {4  const expected = crypto.createHmac('sha256', secret).update(raw).digest('hex')5  return crypto.timingSafeEqual(6    Buffer.from(expected, 'hex'),7    Buffer.from(signature, 'hex')8  )9}

Silsiladda hubinta

Codsi kasta ee aqoonsi waxa lagu saxiixaa ECDSA P-256, lana keydiyaa silsilad muddo-go'an leh. Waxa la weydiin karaa /api/v1/audit, lana xaqiijin karaa internet la'aan.

GET/api/v1/auditbearer

Stream signed audit entries for the authenticated identity.

Parameters

Name	Type	Required	Description
`since`	`ISO 8601`	optional	Filter entries after this timestamp.
`limit`	`integer`	optional	1–500, default 50.

Response

JSON

1{2  "entries": [3    {4      "id": "uuid",5      "event": "kyc.approved",6      "occurred_at": "2026-05-14T08:22:00Z",7      "signature": "ECDSA-P256: MEUCIQ..."8    }9  ],10  "next_cursor": null11}

Xadka codsiyada

Tier	Per minute	Per day	Burst
Public lookup	20	5,000	40
Authenticated	60	50,000	120
Bearer (Growth)	300	1,000,000	600
Sovereign	Aan kooban	—	—

Qaladaadka

Code	HTTP	Description
`invalid_request`	`400`	Missing or malformed parameters.
`invalid_client`	`401`	Client authentication failed.
`invalid_grant`	`400`	Authorization code, refresh token, or PKCE verifier invalid.
`unauthorized`	`401`	Missing or expired access token.
`insufficient_kyc`	`403`	KYC tier too low for this operation. Step-up required.
`identity_suspended`	`403`	Identity has been suspended pending review.
`dpop_required`	`401`	Endpoint requires a DPoP-bound token.
`rate_limited`	`429`	Too many requests; check Retry-After.
`server_error`	`500`	Internal error. Already paged on-call.

Wax laga maqan? Nala xidhiidh.

Eeg Quickstart

Tijaabi

userinfo.curl

cURL

1curl 'https://id.jaalle.com/api/oauth/userinfo' \2  -H 'Authorization: Bearer …'

Riix "Tijaabi API" ee dashboard-ka si aad u ridid codsi nool oo aad arkid jawaabaha.

Tag console-ka

API REFERENCE · OAUTH 2.1 · OIDC

Dukumentiyada JaalleID API.

Endpoint kasta wuxuu raacaa OAuth 2.1, OIDC Discovery, iyo W3C Verifiable Credentials. JSON kaliya. Bearer kaliya. PKCE waa lagama maarmaan.

Guud ahaan

URL-ka ASAASIGA AH

https://id.jaalle.com

AQOONSIGA

Codsiyada lagu hayo magaca isticmaalaha waxa lagu ogolaadaa bearer-token caadi ah. Codsiyada heer-sare waxay isticmaalaan DPoP-binding (RFC 9449) si saxiixyada loo xidho cinwaan-saxiixaha.

OAuth 2.1

PKCE S256 · DPoP

SD-JWT VC

OAuth 2.1 + OIDC

Khadadka OAuth 2.1 caadiga ah, oo lagu xoojiyay PKCE S256 lagama-maarmaan, FIDO2/WebAuthn-step-up, iyo SD-JWT VC issuance.

GET/api/oauth/authorizepublic

Bilow xidhiidh oggolaansho. U haga isticmaalaha halkan si ay ugu soo galaan JaalleID.

Parameters

Name	Type	Required	Description
`client_id`	`string`	required	Your OAuth client identifier.
`redirect_uri`	`string`	required	A redirect URI registered for this client.
`response_type`	`string`	required	Must be "code".
`scope`	`string`	required	Space-separated. e.g. "openid profile email kyc_status trust_score".
`code_challenge`	`string`	required	PKCE S256 challenge — base64url(SHA-256(verifier)).
`code_challenge_method`	`string`	required	Must be "S256". "plain" is rejected.
`state`	`string`	required	Opaque value bound to the user session for CSRF protection.
`prompt`	`string`	optional	"none" · "login" · "consent" · "select_account".

Response

HTTP

1HTTP 307 → ${redirect_uri}?code=AUTH_CODE&state=ORIGINAL_STATE

POST/api/oauth/tokenclient_credentials

Ku beddel code-ka aqoonsi tokens. PKCE verifier waa lagama maarmaan.

Request body

JSON

1{2  "grant_type": "authorization_code",3  "code": "AUTH_CODE",4  "redirect_uri": "https://app.example.so/callback",5  "client_id": "jid_your_client_id",6  "code_verifier": "ORIGINAL_PKCE_VERIFIER"7}

Response

JSON

1{2  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Im...",3  "token_type": "Bearer",4  "expires_in": 900,5  "refresh_token": "rft_dGhpcyBpcyBhIHJlZnJlc2g...",6  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Im...",7  "scope": "openid profile email kyc_status trust_score"8}

Errors

`invalid_grant`	`400`	Code or PKCE verifier mismatch / expired.
`invalid_client`	`401`	Client authentication failed.

GET/api/oauth/userinfobearer

Soo qaad xog-aqoonsigan la xaqiijiyay ee isticmaalaha hadda saxan.

Response

JSON

1{2  "sub": "550e8400-e29b-41d4-a716-446655440000",3  "jaalle_id": "JID-A3K7M9PQ-R2T4",4  "name": "Mohamed Hassan",5  "email": "mohamed@example.com",6  "email_verified": true,7  "phone": "+252615551234",8  "phone_verified": true,9  "kyc_tier": "VERIFIED",10  "trust_score": 78,11  "identity_level": 212}

POST/api/oauth/revokeclient_credentials

Revoke an access or refresh token (RFC 7009).

Request body

JSON

1{2  "token": "rft_dGhpcyBpcyBhIHJlZnJlc2g...",3  "token_type_hint": "refresh_token"4}

Response

HTTP

1HTTP 200 (no body)

POST/api/oauth/introspectclient_credentials

Introspect token state (RFC 7662).

Request body

JSON

1{ "token": "eyJhbGciOi..." }

Response

JSON

1{2  "active": true,3  "scope": "openid profile email",4  "client_id": "jid_your_client_id",5  "sub": "uuid",6  "exp": 17474000007}

DPoP iyo FIDO2

DPOP-BOUND TOKENS · RFC 9449

Markaad rabto in token ku xidho cinwaanka codsiga, ku dar madaxa DPoP. SDK-yada Jaalle waxay si toos ah u maamulaan saxiixyada.

HTTP

1POST /api/v1/wallet/transfer HTTP/1.12Host: id.jaalle.com3Authorization: DPoP eyJhbGciOiJSUzI1NiIsImtpZCI6...4DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2I...

FIDO2 · WEBAUTHN

Step-up authentication adigoo isticmaalaya passkey ama amniga furayaasha hardware.

POST/api/oauth/fido2/challengebearer

Generate a WebAuthn assertion challenge bound to the active session.

Response

JSON

1{2  "challenge": "base64url...",3  "timeout": 60000,4  "rpId": "id.jaalle.com",5  "allowCredentials": [6    { "id": "base64url...", "type": "public-key" }7  ]8}

Aqoonsiga

GET/api/v1/identitybearer

Fetch the current user's full sovereign identity record.

Response

JSON

1{2  "id": "uuid",3  "jaalleId": "JID-A3K7M9PQ-R2T4",4  "kycTier": "VERIFIED",5  "trustScore": 78,6  "identityLevel": 2,7  "fullName": "Mohamed Hassan",8  "dateOfBirth": "1991-04-12",9  "region": "Banaadir",10  "issuedAt": "2025-09-13T08:22:00Z"11}

GET/api/v1/identity/lookuppublic

Public minimal-claim lookup by JIN. Rate-limited.

Parameters

Name	Type	Required	Description
`jaalle_id`	`string`	required	The JIN to look up (JID-XXXXXXXX-XXXX format).

Response

JSON

1{2  "found": true,3  "display_name": "Mohamed H.",4  "verification_level": "L2",5  "trust_score": 786}

KYC

POST/api/v1/verifybearer

Submit a KYC document for verification. Returns immediately with PROCESSING state.

Request body

multipart/form-data

1FormData {2  type: "national_id" | "passport" | "driver_licence"3  file: <binary>4  selfie: <binary>  // optional, required for L3+5}

Response

JSON

1{2  "id": "uuid",3  "status": "PROCESSING",4  "expected_completion": "2026-05-15T12:04:00Z"5}

Verifiable Credentials

OID4VCI ku salaysan SD-JWT VC. 13 nooc oo caddayn ayaa la taageeraa.

POST/api/v1/credentials/offerbearer

Create a credential offer (pre-authorized code flow).

Request body

JSON

1{ "credential_type": "NationalIdentity" }

Response

JSON

1{2  "credential_offer": { "credential_issuer": "...", "credentials": [...] },3  "credential_offer_uri": "openid-credential-offer://...",4  "offer_id": "uuid"5}

POST/api/v1/credentials/issuebearer

Exchange pre-authorized code for an SD-JWT VC.

Request body

JSON

1{2  "grant_type": "urn:ietf:params:oauth:grant-type:pre-authorized_code",3  "pre-authorized_code": "...",4  "proof": { "proof_type": "jwt", "jwt": "..." }5}

Response

JSON

1{2  "credential": "eyJ...~disc1~disc2~",3  "format": "vc+sd-jwt",4  "c_nonce": "..."5}

Webhooks

14 dhacdo

Saxiixa Webhook · HMAC-SHA256

Webhook kasta wuxuu la socdaa madaxa X-JaalleID-Signature oo ah HMAC-SHA256 hex-encoded.

TypeScript

1import crypto from 'crypto'2 3export function verify(raw: string, signature: string, secret: string) {4  const expected = crypto.createHmac('sha256', secret).update(raw).digest('hex')5  return crypto.timingSafeEqual(6    Buffer.from(expected, 'hex'),7    Buffer.from(signature, 'hex')8  )9}

Silsiladda hubinta

Codsi kasta ee aqoonsi waxa lagu saxiixaa ECDSA P-256, lana keydiyaa silsilad muddo-go'an leh. Waxa la weydiin karaa /api/v1/audit, lana xaqiijin karaa internet la'aan.

GET/api/v1/auditbearer

Stream signed audit entries for the authenticated identity.

Parameters

Name	Type	Required	Description
`since`	`ISO 8601`	optional	Filter entries after this timestamp.
`limit`	`integer`	optional	1–500, default 50.

Response

JSON

1{2  "entries": [3    {4      "id": "uuid",5      "event": "kyc.approved",6      "occurred_at": "2026-05-14T08:22:00Z",7      "signature": "ECDSA-P256: MEUCIQ..."8    }9  ],10  "next_cursor": null11}

Xadka codsiyada

Tier	Per minute	Per day	Burst
Public lookup	20	5,000	40
Authenticated	60	50,000	120
Bearer (Growth)	300	1,000,000	600
Sovereign	Aan kooban	—	—

Qaladaadka

Code	HTTP	Description
`invalid_request`	`400`	Missing or malformed parameters.
`invalid_client`	`401`	Client authentication failed.
`invalid_grant`	`400`	Authorization code, refresh token, or PKCE verifier invalid.
`unauthorized`	`401`	Missing or expired access token.
`insufficient_kyc`	`403`	KYC tier too low for this operation. Step-up required.
`identity_suspended`	`403`	Identity has been suspended pending review.
`dpop_required`	`401`	Endpoint requires a DPoP-bound token.
`rate_limited`	`429`	Too many requests; check Retry-After.
`server_error`	`500`	Internal error. Already paged on-call.

Wax laga maqan? Nala xidhiidh.

Eeg Quickstart

Tijaabi

userinfo.curl

cURL

1curl 'https://id.jaalle.com/api/oauth/userinfo' \2  -H 'Authorization: Bearer …'

Riix "Tijaabi API" ee dashboard-ka si aad u ridid codsi nool oo aad arkid jawaabaha.

Tag console-ka