Account directory

The account directory lets a backend service read Raha Account users who are assigned to its application, without a user being present. It is a protected machine-to-machine resource accessed with the Client Credentials grant.

Directory access must be enabled for your application by Raha Account administrators, and only users assigned to your application are visible. See access to protected resources.

1. Discover the resource

GET {API_BASE}/.well-known/oauth-protected-resource/api/v1/directory

This RFC 9728 metadata supplies the exact resource identifier, the authorization server, the bearer method, and the supported scopes.

2. Request a token

Use Client Credentials with the discovered resource:

curl -X POST "$TOKEN_ENDPOINT" \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'resource=DISCOVERED_DIRECTORY_RESOURCE' \
  --data-urlencode 'scope=users:read users:read:email'

Scope	Effect
`users:read`	Required. Read basic account and profile fields.
`users:read:email`	Also return `email` and `email_verified`.
`users:read:phone`	Also return `phone_number` and `phone_number_verified`.

Cache the access token until shortly before expires_in and request a new one when it expires.

3. Read an assigned user

GET {API_BASE}/api/v1/directory/users/{user_id}
Authorization: Bearer {client_credentials_access_token}

user_id is the user's Raha Account ID, the same value as the sub claim your application receives at sign-in.

{
  "id": "6f1c2a4e-1b7d-4d55-9c1e-0a2b3c4d5e6f",
  "username": "example",
  "status": "ACTIVE",
  "profile": {
    "first_name": "Example",
    "last_name": "User",
    "picture": "https://..."
  },
  "email": "user@example.com",
  "email_verified": true
}

status is one of ACTIVE, LOCKED, SUSPENDED, or PENDING_SIGNUP. Email and phone fields appear only when the token has the matching scope. picture is a short-lived URL; do not store it.

Access rules

Only client-credentials tokens issued for the directory resource are accepted.
Users must be assigned to your application directly or through a role.
Missing and unassigned users both return 404, so the response never reveals whether an account exists.
If administrators change your application's grant, tokens issued before the change are rejected; request a new token.
Error responses include a WWW-Authenticate challenge with resource_metadata pointing back to the discovery URL.