OAuth 2.0

Use OAuth 2.0 when your application needs to act on behalf of an Ummat user. Ummat implements Authorization Code + PKCE (for user-facing apps) and Client Credentials (for server-to-server access).

OIDC discovery

Ummat publishes an OpenID Connect discovery document:

GET https://api.ummat.dev/.well-known/openid-configuration

Register an OAuth client

Request a client from Developer › OAuth Clients. Your application will be reviewed before approval. You need:

App name and description
Redirect URIs (must be HTTPS in production)
Requested scopes

Once approved you receive a client_id and (for confidential clients) a client_secret.

Authorization Code + PKCE

For public clients (mobile apps, SPAs). PKCE is required — plain is rejected.

1. Generate a code verifier and challenge

const verifier = crypto.randomBytes(32).toString('base64url');
const challenge = crypto
  .createHash('sha256')
  .update(verifier)
  .digest('base64url');

2. Redirect to the authorization endpoint

GET https://api.ummat.dev/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=masjid:read prayer-times:read
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_CHALLENGE
  &code_challenge_method=S256

3. Exchange the code for tokens

POST https://api.ummat.dev/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=https://yourapp.com/callback
&client_id=YOUR_CLIENT_ID
&code_verifier=CODE_VERIFIER

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "rt_xxxxxxxxxxx",
  "scope": "masjid:read prayer-times:read"
}

Client Credentials

For server-to-server access with no user context. Confidential clients only.

POST https://api.ummat.dev/api/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(client_id:client_secret)

grant_type=client_credentials
&scope=masjid:read

Refreshing tokens

POST https://api.ummat.dev/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=rt_xxxxxxxxxxx
&client_id=YOUR_CLIENT_ID

Revoking tokens

POST https://api.ummat.dev/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=TOKEN_TO_REVOKE
&client_id=YOUR_CLIENT_ID

UserInfo endpoint

GET https://api.ummat.dev/api/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

{
  "sub": "user-uuid",
  "email": "[email protected]",
  "name": "Ahmad Al-Farsi",
  "picture": "https://storage.ummat.dev/avatars/uuid.jpg"
}

Scopes

OAuth tokens use the same scope system as API keys. See Authentication › Key scopes for the full list.