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 —Documentation Index
Fetch the complete documentation index at: https://empuls.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
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 instead — simpler, scoped at the event level.
How OAuth in Empuls works
Register a client
Provide a name, callback URL, and the allowed scopes. Empuls returns a client ID and a client secret.
Restrict client by company
Optionally limit the client to a specific company ID (multi-tenant scenarios) or set of company IDs.
User authorization flow
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.Client exchanges code for tokens
The client’s backend exchanges the authorization code at
/token for an access token and refresh token.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 |
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 |
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:- The client makes a request to the
generateLimitedAccessTokenmutation with the desired scopes. - Empuls returns a short-lived token (15 minutes default).
- The client uses the token for the operation, then it expires.
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.
Retry-After header.
Register a client
Until a self-service UI exists, register clients by contacting cs@xoxoday.com with:- Client name and description
- Callback URL(s)
- Required scopes (justification helpful)
- Company restriction (if applicable)
- Contact owner
Revoke a client
To revoke a client (e.g., the partner relationship ends or credentials leaked):- Contact Empuls support with the client ID.
- 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
- Webhook & APIs — Simpler event-driven integration alternative.
- SSO overview — User-facing identity federation (different from API access).
- Access control — In-Empuls RBAC, which OAuth scopes also respect.