OAuth 2
This guide explains OAuth 2.0 authentication with Factorial HR and the two token types available. For step-by-step setup with Postman examples, see the Company Token and User Token guides.
Prerequisites
Before starting, make sure you have:
- Admin access to Factorial HR
- Access to the correct environment (Production or Demo), with Settings → Advanced configuration → OAuth applications available to your admin user (Production)
- Postman access through browser or application
- For the user token: a user assigned a specified permissions group
How to choose your environment: Environments: Production and Demo
Understanding Token Types
🏢 Company Token
A Company Token provides company-wide access to Factorial data. All actions are performed on behalf of the company, not a specific user.
| Property | Details |
|---|---|
| Lifetime | 1 hour (requires refresh token to renew) |
| Use case | Integrations that need full company data without user interaction |
| Permissions | Full access to all company data |
👤 User Token
A User Token provides user-scoped access. All actions are performed on behalf of a specific employee, and access is limited by that employee's permission group.
| Property | Details |
|---|---|
| Lifetime | 1 hour (requires refresh token to renew) |
| Use case | Integrations with restricted access, hiding sensitive data from third parties |
| Permissions | Limited to the employee's permission group |
OAuth applications
OAuth applications are created and managed by a Factorial admin in Settings → Advanced configuration → OAuth applications (open OAuth applications in Factorial). There you configure the application name, redirect URIs, scopes, client type, and client credentials.
Client types
When you create an OAuth application you choose how it authenticates:
| Client type | In Factorial | Runs on | Authenticates with |
|---|---|---|---|
| Confidential | Confidential client with secret | A trusted backend that can keep a client secret private | Client secret when exchanging the authorization code for tokens |
| Non-confidential (public) | Public client without secret | Browser SPAs, mobile apps, or desktop apps, where a secret cannot be protected | Authorization Code + PKCE (no client secret) |
- Confidential clients run on a trusted backend and can keep a client secret private. They authenticate with that secret when exchanging an authorization code for tokens.
- Non-confidential (public) clients run in environments where a secret cannot be protected, such as browser SPAs, mobile apps, or desktop apps. A client secret would be extractable, so it must not be relied on for authentication.
Public clients should use Authorization Code + PKCE
- Generate a random
code_verifierlocally.- Derive a
code_challengefrom it and send that with the authorization request.- Keep the verifier only in the client.
- Send the original verifier when exchanging the returned code for tokens.
Factorial ID endpoints
| Endpoint | Production | Demo |
|---|---|---|
| Authorize | https://id.factorialhr.com/oauth/authorize | https://id.eu2.demo.factorial.dev/oauth/authorize |
| Token (exchange and refresh) | https://id.factorialhr.com/api/oauth/token | https://id.eu2.demo.factorial.dev/api/oauth/token |
| Revoke | https://id.factorialhr.com/api/oauth/revoke | https://id.eu2.demo.factorial.dev/api/oauth/revoke |
Existing integrations can keep their current endpoints while they are migrated.
Support
If you have any issues or questions about the API, don't hesitate to get in touch with our Tech Support team by filling out one of the following forms:
Updated 1 day ago