Quickstart

Integrating with Raha Account takes three steps: register your application, pick the flow that matches how your application runs, and validate the tokens you receive. Use the hosted authorization flow for user sign-in, and never collect Raha Account passwords inside your application.

1. Register your application

Create an application in Raha Account to get a client_id (and a client_secret for confidential clients). Register every redirect URI exactly as your application will send it. See Register an application.

2. Find your endpoints

A Raha Account deployment may use separate issuer and API origins:

ISSUER: discovery, hosted sign-in, and account pages.
API_BASE: /api/oauth2 protocol endpoints and /api/v1 resource APIs.

Always read the actual URLs from the discovery document instead of building them by hand:

curl "$ISSUER/.well-known/openid-configuration"

The response includes authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, end_session_endpoint, device_authorization_endpoint, and the scopes, grant types, and client authentication methods the deployment supports.

3. Choose a flow

Your application	Flow
Web app, SPA, or mobile app that signs users in	Authorization Code + S256 PKCE
Needs to stay signed in while the user is away	Refresh tokens with the `offline_access` scope
TV, CLI, or other device without a convenient browser	Device Authorization Grant
Backend service that reads users assigned to your app	Client Credentials with the account directory

Scopes

Scope	Grants
`openid`	Enables OpenID Connect, issues an ID token, and is required for UserInfo.
`profile`	Name and profile picture claims.
`email`	Email address and verification status.
`phone`	Phone number and verification status.
`offline_access`	A refresh token, after the user consents to offline access.
`users:read`	Account directory: read users assigned to your application.
`users:read:email`	Account directory: include email fields. Requires `users:read`.
`users:read:phone`	Account directory: include phone fields. Requires `users:read`.

Request only the scopes you need. Users see the requested scopes on the consent screen, and the granted set may be smaller than what you asked for.

Next steps

Follow the web application guide end to end.
Learn how sign-in, sessions, and logout behave.
Match the hosted pages to your app with hosted UI preferences.
Use an SDK if one exists for your stack.