Authentication methods
Factorial's public API supports two authentication methods: API Keys and OAuth 2.0. Choosing the right one depends on what you're building and who will use it.
Prefer to watch instead of read?
This short walkthrough covers both authentication methods end‑to‑end — creating an API Key and completing the full OAuth 2.0 flow (Company Token and User Token) in Postman. Watch it first if you'd rather see it in action, then use the written guide below as your reference while you build.
Which Method Should I Use?
| API Key | OAuth 2.0 | |
|---|---|---|
| Best for | Internal company integrations | Marketplace integrations and third-party apps |
| Setup complexity | Low: generate and use immediately | Higher: requires an OAuth application and token exchange flow |
| Access scope | Full access to all scopes | Configurable - scopes and permissions can be set |
| Expiry | Does not expire | Company Token: no expiry / User Token: 1 hour |
| Marketplace use | ⚠️ Deprecated — being phased out | ✅ Required |
| Internal use | ✅ Supported | ✅ Supported |
API Keys
API Keys are the fastest way to start making requests to the Factorial API. You generate a key from your company settings and include it in every request — no authorization flow required.
Use API Keys when:
- You are building an internal tool or script for your own company
- You need a quick integration without user interaction
- You are not distributing the integration to other companies
API Keys always grant access to all available scopes. If your integration should only access a subset of company data, use OAuth 2.0 and restrict the application scopes accordingly.
OAuth 2.0
OAuth 2.0 is the standard for building integrations that act on behalf of a company or a specific user. It provides a secure, auditable token exchange and supports two token types: a Company Token for full company access, and a User Token for scoped, user-level access.
Use OAuth 2.0 when:
- You are building a marketplace integration that other companies will connect to
- You need to restrict what data the integration can access (User Token)
- You need a standardised, secure authentication flow that HR admins can authorize themselves
OAuth 2.0 is required for all marketplace integrations. It also works for internal integrations if you need finer access control than an API Key provides.
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 20 days ago