Partner guide - Company token
This article will explain how to obtain company token to integrate Factorial with other software programs. The OAuth application will be generated by the Factorial Development team.
Main advantages
- It won't expire (has unlimited time)
- Anyone can use it (in case the company provides permission to connect with it)
- Has all permissions enabled (like an API KEY)
Step 1 - Factorial creates an OAuth App for the partner
The whole process can be tested in a demo environment as well. So if this is your purpose, you can create your OAuth App in a demo environment here.
Production environment URL: https://api.factorialhr.com
Demo environment URL: https://api.demo.factorialhr.dev
In this initial step, Factorial will create your OAuth Application (only for production). To accomplish this, we require the partner to provide us with a redirect_uri
to facilitate the OAuth App creation process. This redirect_uri
is the endpoint in which the partner will receive the authorization code (this will be described in next step).
For Factorial to create your OAuth Application in Production, you can fill this form
Upon creation of the OAuth App, we will share to the partner via Keeper the following information:
client_id
: The unique identifier for the appclient_secret
: The confidential code for secure communication
You will receive a link of Keeper that will get you to a page similar to the image below. If you want more info about the way about how Keeper so it you can visit this link
Step 2 - Request authorization code:
As part of the OAuth 2 protocol, the action should be started by the Factorial user. As we are asking a company_token
, it is important that before clicking it a Factorial admin is logged. The link you should provide to your client is:
https://api.factorialhr.com/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&resource_owner_type=company
⚠️ NOTE: Before this initiative, Factorial already allowed users OAuth tokens. Right now the difference is that you will request a company token with this last parameter: resource_owner_type=company
Without this parameter, you will request a user one.
Before granting an authorization code, the admin should authorize the permissions needed for your app.
The following picture is an example of how the grant screen displays:
Upon clicking "Authorize," the user will be redirected to the redirect_uri
with the generated code. An example of the resulting URL is as follows:
https://embeddedapp.com?code=examplecode123
Then the Partner app receives the code and initiates the process of obtaining an access token.
Final Step:
To get a company access token from the partner app server you will need to do a POST request with the following parameters:
client_id
= the one we sent you when creating the OAuth Appclient_secret
= the one we sent you when creating the OAuth Appcode
= (the one you received previously with the GET request = codeexample123)redirect_uri
= the one you sent us for us to create the OAuth Appgrant_type
= authorization_code
So it would look like the following url:
POST - https://api.factorialhr.com/oauth/token?client_id={client_id}&client_secret={client_secret}&code={code}&redirect_uri={redirect_uri}&grant_type=authorization_code
And you will get a response like in the following picture:
Good Job!
Following these steps, you should now be able to make requests to our API using the access_token
as a Bearer token for authorization.
You will only had to add a header in your requests like this:
Authorization: ‘Bearer {access-token}
Here's an example picture illustrating the process (OAuth):
Note: You can still use both API Keys and OAuth company token until you finish your migration and switch everyone to OAuth.
Diagram flow
Updated 12 days ago