Create the OAuth Application

A Factorial admin creates and manages OAuth applications in Settings → Advanced configuration → OAuth applications.

➡️Open OAuth applications in Factorial

1. In Factorial, open Settings.
2. Under Advanced configuration, select OAuth applications.
3. Select Create OAuth app.
4. Enter the application name, one redirect URI per line, and the scopes the integration needs. To test with Postman, use one of these redirect URIs:

   • Postman in browser: https://oauth.pstmn.io/v1/browser-callback

   • Postman desktop: https://oauth.pstmn.io/v1/callback

   If you have doubts about which scopes to apply, you can contact Factorial support.

5. Choose the client type:
   • Confidential client with secret if the application can store a client secret securely on a server.
   • Public client without secret for browser, desktop, or mobile applications that cannot keep a secret.
6. Select Save.

After saving, the OAuth applications page shows the application name, client ID, scopes, and redirect URIs.

Choose the client type

• 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.

Save Client ID and Client Secret

1. The Client ID is always visible in the OAuth applications list.
2. A client secret is created only for a Confidential client with secret. Copy it when it is shown and store it securely.
3. Verify the redirect URIs and scopes are saved correctly.

Start the authorization request

The OAuth applications page does not start authorization for you. After creating the application, your integration must send the company administrator to the Factorial ID authorization endpoint. For a company-owned flow, use the application's client ID and registered redirect URI, and add resource_owner_type=company:

https://id.factorialhr.com/oauth/authorize?client_id=<CLIENT_ID>&redirect_uri=<URL_ENCODED_REDIRECT_URI>&response_type=code&scope=<URL_ENCODED_SCOPES>&state=<RANDOM_STATE>&resource_owner_type=company

For demo, use https://id.eu2.demo.factorial.dev/oauth/authorize with the same parameters.

Public clients (PKCE): also add &code_challenge=<CODE_CHALLENGE>&code_challenge_method=S256, where code_challenge is derived from the code_verifier your client generated and kept locally.

1. The administrator signs in to Factorial, reviews the requested scopes, and authorizes the application.

2. Factorial then redirects to the registered redirect URI with the authorization code.

3. The URL of that page contains your Authorization Code. For example:

https://oauth.pstmn.io/v1/browser-callback?code=elX2bzbV85mS90PU8319-mqxLcl-1MgSmuQlas33gw

In this example, the code is: elX2bzbV85mS90PU8319-mqxLcl-1MgSmuQlas33gw. If you sent a state value, check that the one returned matches it.

Exchange Code for Access Token

Use Postman to request the token.

1. In Postman, go to My Collection → Get data → Authorization.
2. Set the Auth Type to OAuth 2.0.

3. Fill in the Configure New Token section with the following Factorial ID values:

For a Public client without secret, set Grant Type to Authorization Code (With PKCE) and leave Client Secret empty. Postman generates the code_verifier and code_challenge for you.

4. Scroll down to Auth Request and add a query parameter:
   • Key: code
   • Value: Your Authorization Code from the previous step

5. Click the orange "Get new access token" button.

6. In the pop-up window, sign in to Factorial if needed, review the requested scopes, and click "Authorize".
7. After authorization, a pop-up in Postman will return your Access Token.

Exchange the code without Postman

Send a POST request to the Factorial ID token endpoint.

Confidential client

curl -X POST 'https://id.factorialhr.com/api/oauth/token' \
  -d 'client_id=<CLIENT_ID>' \
  -d 'client_secret=<CLIENT_SECRET>' \
  -d 'code=<AUTHORIZATION_CODE>' \
  -d 'redirect_uri=<REDIRECT_URI>' \
  -d 'grant_type=authorization_code'

Public client (PKCE): do not send a client secret; send the original code_verifier instead.

curl -X POST 'https://id.factorialhr.com/api/oauth/token' \
  -d 'client_id=<CLIENT_ID>' \
  -d 'code=<AUTHORIZATION_CODE>' \
  -d 'redirect_uri=<REDIRECT_URI>' \
  -d 'code_verifier=<CODE_VERIFIER>' \
  -d 'grant_type=authorization_code'

For demo, use https://id.eu2.demo.factorial.dev/api/oauth/token.

Video walkthrough

Refreshing Access Token

Company access tokens are valid for one hour. After this period has expired, request a new access token with a POST request to the Factorial ID token endpoint, providing the refresh token that came with the previous access token.

curl -X POST 'https://id.factorialhr.com/api/oauth/token' -d 'client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>&refresh_token=<REFRESH_TOKEN>&grant_type=refresh_token'

Public clients: omit client_secret.