Raha Account Developer Documentation

Raha Account is the identity platform for Raha applications. It gives people one account across every connected application and lets your application sign them in, read the profile data they approve, and call protected APIs, all through standard OAuth 2.0 and OpenID Connect.

What Raha Account provides

• Single sign-on. Users sign in once with their Raha Account and use it with any registered application.
• Hosted sign-in. Raha Account hosts login, signup, multi-factor authentication, account selection, password recovery, and consent. Your application never handles a Raha Account password.
• Standards-based tokens. Applications receive signed ID tokens and access tokens through OpenID Connect and OAuth 2.0, so any standards-compliant OIDC client library works.
• User consent. Users choose which profile data an application may read, and can revoke an application at any time from their account.
• Machine access. Backend services can read the users assigned to their application through the account directory, using client credentials.
• Localized experience. Hosted pages support English, Persian/Dari, and Pashto, with light and dark themes that can follow your application.

Core concepts

Concept	Description
Account	A person's Raha Account identity. Its stable identifier is the token sub claim.
Application (client)	Your registered OAuth/OIDC client, identified by a client_id. It is either public (SPA, mobile, CLI) or confidential (backend).
Issuer	The Raha Account origin that signs tokens and publishes /.well-known/openid-configuration.
Scope	A permission your application requests, such as openid, profile, or email. Users approve scopes during consent.
Session	The user's Raha Account sign-in session. It is separate from your application's own session.
Protected resource	A Raha API that only accepts access tokens issued for its audience, such as the account directory.

How an integration works

1. Register your application and its exact redirect URIs.
2. Load /.well-known/openid-configuration from the issuer to discover endpoints.
3. Redirect the user to the authorization endpoint using Authorization Code with S256 PKCE.
4. Raha Account authenticates the user, collects consent, and redirects back to your application with a code.
5. Exchange the code for tokens, then validate the ID token's issuer, audience, signature, expiry, and nonce.
6. Send access tokens as Authorization: Bearer {token} only to their intended audience.

The quickstart helps you choose the right flow for your application type.

API conventions

• Protocol endpoints use /api/oauth2 without a version segment. Resource APIs use /api/v1.
• JSON request and response fields use snake_case.
• Authentication responses are not cacheable unless an endpoint says otherwise.
• You may send x-request-id with requests. Error responses include x-reference-id for support correlation.
• Discover endpoints from the issuer instead of copying URLs between environments.