GuidesAPI ReferenceChangelog
Guides

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.

Create a Permission Group

Restrict the employee's access to only what the integration needs.

Go to Settings → Permissions → New Custom Group and select the permissions the integration should be limited to. This ensures the integration can only see and modify data you explicitly allow.

Create a Dedicated Employee or External User Account

Set up an employee account that will own the user token.

  1. Create a new employee in Factorial with a descriptive name (e.g., Integration User - Provider Name). Use a real email address you have access to, as Factorial will send an activation email.
  2. If you outsource integration management to an external provider, you can invite them as an External User in your company settings.

Activate the Employee Account

The employee receives an activation email and sets their password.

Check the email inbox for the activation message. Click the link and set a password for the new account.

Create the OAuth Application (if not done already)


Register a new OAuth application in Factorial as an admin.

  1. Log in to Factorial with your admin account and navigate to the OAuth applications page:
  2. Click the "New Application" button to create a new application.

Configure Application Settings

Fill in the application details with the Redirect URI and scopes.

  1. Enter the Application Name (for example, the name of the software you're integrating).

  2. Enter the Redirect URI:

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

  3. Select the scopes you will need for your integration.

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

  4. Click "Submit".

Save Client ID and Client Secret

Copy the credentials — the Client Secret is only shown once.

  1. Copy and save the Client Secret in a safe location — it cannot be regenerated if lost.
  2. The Client ID will always be accessible from the application settings.
  3. Verify the Redirect URI and Scopes are saved correctly.
⚠️

Important: The Client Secret is shown only once. Store it securely immediately.

Generate Authorization Code (User Token)

Log in as the integration employee or external user and authorize the application.

⚠️

Important: Since only admins can access the OAuth applications panel, the admin must build the authorization URL and share it with the integration employee or external user. That user opens the link while logged into Factorial.

  1. Build a URL to share with the user as follows:

    https://api.factorialhr.com/oauth/authorize?client_id=<YOUR_CLIENT_ID>&redirect_uri=<YOUR_REDIRECT_URI>&response_type=code

    Where:

    • YOUR_CLIENT_ID = Client ID of your application
    • YOUR_REDIRECT_URI = Redirect URI set when creating your application

  2. Alternatively, right-click the green "Authorize" button and select Copy Link Address.


Once the user accesses the URL, the Authorization Code will be attached at the end of the redirect URL. For example:

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

Exchange Code for Access Token

Use Postman to exchange the authorization code for an access token.

  1. In Postman, go to My Collection → Get data → Authorization.
  2. Set the Auth Type to OAuth 2.0.
  1. Fill in the Configure New Token section with the following values:
FieldProductionDemo
Auth URLhttps://api.factorialhr.com/oauth/authorizehttps://api.eu2.demo.factorial.dev/oauth/authorize
Access Token URLhttps://api.factorialhr.com/oauth/tokenhttps://api.eu2.demo.factorial.dev/oauth/token
Client IDYour Client ID from the applicationYour Client ID from the application
Client SecretYour Client Secret from the applicationYour Client Secret from the application


  1. Scroll down to Auth Request and add a query parameter:
    • Key: code
    • Value: Your Authorization Code from step A4
  1. Click the orange "Get new access token" button.
  1. In the pop-up window, click "Authorize" again.
  1. After authorization, a pop-up in Postman will return your Access Token.

⏰

User Token Expiry: User tokens expire after 1 hour. Save the refresh_token to request new access tokens without re-authorizing.


Refreshing Access Token

User access tokens are valid for a period of one hour. After this period has expired, you will need to request a new access token with a POST request, providing the refresh token that came with the first access token.

🚧

Note

Non-admin users can perform this action as long as they have the refresh token provided at time of first authentication.

❗️

Important

The refresh access token will last 1 week. In case you are over one week, you will need to start the process all over again.

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

Revoking Access Token

You can revoke an access/refresh token if you do not want it to remain active. This can be necessary in cases where you feel a token has been compromised.

🚧

Note

Using a new token automatically revokes the previous token, and hence an API call is not necessary for that.

curl -X POST 'https://api.factorialhr.com/oauth/revoke' -d 'client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>&token=<TOKEN>'

YOUR_CLIENT_ID: OAuth2 Application Id

YOUR_CLIENT_SECRET: OAuth2 Application Secret

TOKEN: OAuth2 Access/Refresh Token (whichever you wish to revoke)

Updated 20 days ago

Did this page help you?