Permissions & Scopes

Control what your app can access through OAuth scopes.

Proma uses OAuth 2.0 scopes to control what your app can do on behalf of a user. Users explicitly grant permissions during the authorization flow.

Available Scopes

Scope	Description
`profile:read`	Read the user's name, email, and avatar
`credits:read`	Check the user's credit balance
`credits:spend`	Spend credits from the user's balance

How Scopes Work

When a user logs into your app through Proma, they see a consent screen listing the permissions you've requested. They must approve before your app gets access.

const proma = new PromaClient({
  clientId: 'your-client-id',
  redirectUri: '/callback',
  // Scopes are requested during login
  scopes: ['profile:read', 'credits:read', 'credits:spend'],
});

Principle of Least Privilege

Only request the scopes your app actually needs:

Read-only app (e.g. analytics dashboard): profile:read, credits:read
Credit-spending app (e.g. AI tool): profile:read, credits:read, credits:spend

Users are more likely to authorize apps that request fewer permissions.

Scope Enforcement

Proma enforces scopes at the API level. If your app tries to spend credits without the credits:spend scope, the API returns a 403 Forbidden error. You don't need to check scopes yourself — the platform handles it.

User Control

Users can revoke your app's access at any time from their Proma account settings. When access is revoked, your app's tokens are invalidated and API calls will fail with a 401 Unauthorized error.

Handle this gracefully by redirecting the user to re-authorize:

try {
  await proma.credits.spend({ amount: 5, description: 'Action' });
} catch (error) {
  if (error.status === 401) {
    // Token revoked, re-authenticate
    proma.loginWithRedirect();
  }
}