Request an access token

Once your user provides you with their authorization code, you can request their access token to Factorial. This is done via a POST request to the following URL:

🚧
Note
Non-admin users can perform this action as long as they have the Oauth Application credentials

curl -X POST 'https://api.factorialhr.com/oauth/token' -d 'client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>&code=<AUTHORIZATION_CODE>&grant_type=authorization_code&redirect_uri=<REDIRECT_URI>'

YOUR_CLIENT_ID: OAuth2 Application Id
YOUR_CLIENT_SECRET: OAuth2 Application Secret
AUTHORIZATION_CODE: OAuth2 CODE
REDIRECT_URI: OAuth2 Redirect URL

https://api.factorialhr.com/oauth/token?client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>&code=<AUTHORIZATION_CODE>&grant_type=authorization_code&redirect_uri=<REDIRECT_URI>

YOUR_CLIENT_ID: OAuth2 Application Id
YOUR_CLIENT_SECRET: OAuth2 Application Secret
AUTHORIZATION_CODE: OAuth2 CODE
REDIRECT_URI: OAuth2 Redirect URL

The CLIENT_ID, CLIENT_SECRET and REDIRECT_URI variables are available in the OAuth application page which can be accessed from your repository of OAuth applications.

The AUTHORIZATION_CODE should either be provided to you by your integration's users or, in case of single-user integrations, you should already have it as described in the previous step of this guide.

The response to this request will have the following shape:

{
 "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
 "token_type": "Bearer", 
 "expires_in": 7200,
 "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1",
 "scope": "read write",
 "created_at": 1680013957
}

Congratulations! With this token, your integration is now able to make requests to Factorial's API. You just need to pass the access token in the HTTP Authorization header as such: Authorization: Bearer <ACCESS_TOKEN>.

You can generate only one OAuth2 token with the same code, you should refresh your token.

Every time a new token is generated a refresh token is generated as well, so that you can use it as the OAuth2 Refresh Token, and an expiry date is also provided.

Now that you are authorized and authenticated to use Factorial's API, you might want to check out our API reference. Happy hacking!

❗️
Access token expiration
All access tokens are valid for a period of one hour. After this period has expired, you will need to request a new access token via a POST request providing the REFRESH_TOKEN that came with the expired access token. See how to do it here.

Steps in Postman 🟠

Go to your Postman account > paste the factorial URL (https://api.factorialhr.com/api/v1/me) > select Authorization OAuth 2

Scroll to the "Configure a new token" section

The links to make it faster 🤗

Auth URL: https://api.factorialhr.com/oauth/authorize
Access Token URL: https://api.factorialhr.com/oauth/token
The callback URL has to be the same as the repository (The callback URL has to be the same in Postman as in the repository.) In case it´s not the same, go to the repository and edit the URL

Client ID and Client secret should be taken from the repository by the ADMIN

Click on "Request new access token"

Use the Token!