> ## Documentation Index
> Fetch the complete documentation index at: https://help-empuls.xoxoday.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OAuth clients and scopes
> Register OAuth client applications, scope-limit them by permission, and issue short-lived limited-access tokens for third-party integrations with Empuls.
Empuls exposes its GraphQL API to third-party applications via OAuth 2.0. You register a client (with its callback URL and allowed scopes), the client redirects users to Empuls for consent, and Empuls issues a token the client uses for subsequent API calls. Scopes are granular — `points_manage`, `budget_read`, `surveys_manage`, etc. — so a client only gets the permissions it actually needs. There's no admin UI for client registration today; it's configured via Empuls support. This page documents the model.
## Before you start
* You must be a **Super Admin** to authorize new clients.
* Confirm with the third-party integration owner exactly which scopes they need; over-broad scopes are a common security finding in audits.
* For internal-only integrations, consider [webhook & APIs](/admin/integrations/other/webhook) instead — simpler, scoped at the event level.
## How OAuth in Empuls works
Provide a name, callback URL, and the allowed scopes. Empuls returns a client ID and a client secret.
Optionally limit the client to a specific company ID (multi-tenant scenarios) or set of company IDs.
A user redirects from the client to Empuls's `/authorize` endpoint. Empuls authenticates the user, shows the requested scopes, and on consent issues an authorization code.
The client's backend exchanges the authorization code at `/token` for an access token and refresh token.
The access token is passed in the `Authorization: Bearer ...` header. Scope enforcement happens server-side — calls outside the granted scopes are rejected.
## Scope catalog
A non-exhaustive list of scopes the API supports:
| Scope | Allows |
| --------------------- | -------------------------------------------------- |
| `points_manage` | Add or deduct reward points |
| `points_read` | Read points balances and history |
| `budget_read` | Read budget configuration and balances |
| `budget_manage` | Create or update budgets |
| `recognitions_read` | Read recognition events |
| `recognitions_create` | Submit new recognitions |
| `surveys_read` | Read survey responses (subject to anonymity rules) |
| `surveys_manage` | Create or update surveys |
| `users_read` | Read employee directory |
| `users_manage` | Create, update, or deactivate employees |
Empuls's full scope list is available via the `oauth_scopes` config — request it from Empuls support when registering.
## Company OAuth tokens vs user OAuth tokens
| Token type | Lifetime | Use case |
| ------------------------ | ----------------------------------------------- | ------------------------------------------ |
| **User OAuth token** | Default 7 days; refreshable | Per-user interactive flows |
| **Company OAuth token** | Default 30 days; refreshable | Service-to-service (HRIS sync, batch jobs) |
| **Limited-access token** | Short-lived (e.g., 15 minutes); not refreshable | One-off operations with elevated scope |
Pick the right token type for the integration. Most HRIS-style integrations use company OAuth tokens.
## Limited-access tokens
For sensitive operations — e.g., a one-time bulk import that needs admin scope — generate a limited-access token instead of granting permanent admin scope:
1. The client makes a request to the `generateLimitedAccessToken` mutation with the desired scopes.
2. Empuls returns a short-lived token (15 minutes default).
3. The client uses the token for the operation, then it expires.
This pattern prevents permanent admin-scope token leakage while still enabling one-off elevated operations.
## CSRF protection
All write mutations require a CSRF token. Clients fetch the CSRF token via a separate `@csrf` directive flow and pass it on every state-changing call. Empuls validates the CSRF on every mutation. Reads (queries) are CSRF-exempt.
## Rate limiting
Per-IP rate limits apply to the GraphQL endpoint:
* Default: 60 requests per minute per IP.
* Authenticated requests: 120 per minute per token.
* Limits configurable per-tenant via support.
Exceeding limits returns 429 Too Many Requests with a `Retry-After` header.
## Register a client
Until a self-service UI exists, register clients by contacting [cs@xoxoday.com](mailto:cs@xoxoday.com) with:
* Client name and description
* Callback URL(s)
* Required scopes (justification helpful)
* Company restriction (if applicable)
* Contact owner
Empuls support provisions the client and returns the credentials securely.
## Revoke a client
To revoke a client (e.g., the partner relationship ends or credentials leaked):
1. Contact Empuls support with the client ID.
2. Empuls revokes the client immediately. All existing tokens become invalid; any in-flight session ends.
## Limits and gotchas
* Client secrets cannot be retrieved after registration. If lost, rotate by contacting support.
* Refresh tokens are single-use — using a refresh token returns a new access + new refresh token. Reuse of an already-used refresh token is rejected.
* Scope grants are sticky — once a user consents to a scope, subsequent token issuances inherit the consent. Revoke and re-consent to change scopes.
* The OAuth surface is part of the auth microservice (`etpauth`). Service availability is independent of Empuls's main app.
## Related
Simpler event-driven integration alternative.
User-facing identity federation (different from API access).
In-Empuls RBAC, which OAuth scopes also respect.