Getting started with Factorial - Authentication

The public API provides two methods of authentication, ApiKeys and OAuth2. The following sections provide information regarding each one and their intent.

ApiKeys

ApiKeys are a single string of symbols that must be added as a custom header on the request. The header name must be x-api-key and the key must be the value without any prefixes.

📘

Use

API keys are used to identify systems, not the individual users that access.

ApiKeys have TOTAL ACCESS to everything and never expire. Its the creators responsability to generate them and store them securely.

The API Key should be passed in the request header as x-api-key

eg

curl --location --request GET 'API-END-POINT' --header 'x-api-key: YOUR-API-KEY'

📘

API KEY Generation

An administrator should generate the KEY from the user interface following this guide
You can also manage KEYS via API, check Core > Keys section.

DISCLAIMER
ApiKey management require full admin permissions as the resource itself allows for full admin access to the entire platform on behalf of the company and not of a user, therefore any operations are not linked to any user in particular.

OAuth 2.0

📘

Use

OAuth2 is used to identify individual users, not applicatins or platforms.

OAuth2 is available for authenticating to the public API and making requests via third parties on behalf of a user. All actions are authored on behalf of the user that creates the token. This means the intent is to be used mainly to do submit actions the actual user is performing on an alternative interface.

To generate a token you will require opening an authorization dialog that returns a code, this code can then be exchanged for a token.

CONFIGURATION
In order to create an OAuth application, you must be an admin, head over to your personal repository of OAuth applications, click on New application and follow the creation process.

The Factorial API enforces the same permissions at the user level than the Factorial web application. This means that Factorial API users will only be able to perform the same actions they are allowed to do in the Factorial platform.

Next step will be to generate the Authorization Code you will need in order to generate an OAuth2 Token.

OAUTH2 CODE GENERATION
Should be generated via browser by opening the following url. The user should be already logged in to Factorial beforehand.

https://api.factorialhr.com/oauth/authorize?client_id=&redirect_uri=&response_type=code&scope=

YOUR_CLIENT_ID: OAuth2 Application Id
REDIRECT_URI: OAuth2 Redirect URL

State Parameter
An optional query parameter called state can be added to the code generation url. Any string can be used and will be sent on the callback url.

Authorization protocols provide a state parameter that allows you to restore the previous state of your application. The state parameter preserves some state objects set by the client in the Authorization request and makes it available to the client in the response.

OAUTH2 TOKEN GENERATION
Once you have the authorization code, you can request their access token to Factorial.

curl -X POST 'https://api.factorialhr.com/oauth/token' -d 'client_id=&client_secret=&code=&grant_type=authorization_code&redirect_uri='
YOUR_CLIENT_ID: OAuth2 Application Id
YOUR_CLIENT_SECRET: OAuth2 Application Secret
AUTHORIZATION_CODE: OAuth2 CODE
REDIRECT_URI: OAuth2 Redirect URL

You can generate only one OAuth2 token per Code, that means that if you want to generate a new token for a Code that already have one 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 on the OAuth2 Refresh Token, and an expire date is also provided.

OAUTH2 REFRESH TOKEN
You can generate a new token under the same Code with a new expire date (you can do it as many times as you need). A refresh token is also returned here so that you can use it on the OAuth2 Refresh Token again.

curl -X POST 'https://api.factorialhr.com/oauth/token' -d 'client_id=&client_secret=&refresh_token=&grant_type=refresh_token'
YOUR_CLIENT_ID: OAuth2 Application Id
YOUR_CLIENT_SECRET: OAuth2 Application Secret
REFRESH_TOKEN: OAuth2 Refresh Token

OAUTH2 TOKEN USAGE
The generated token is the credential for performing authenticated requests to Factorial. This token should be included in the Authorization header prefixed with the word Bearer and a separating space.
As an example, if your token is 12345 then the header content should be Bearer 12345.

MAINTAINING A PERSISTENT CONNECTION
To maintain a persistent connection, you should not let the token expire. You can avoid this by simply refreshing your token before the expiration date. This will give you another token with a new expiration date, before that token expires you should refresh it again, and so on...
If you want to do this automatically, you should provide something in your code that will help you perform the update every time the token expires. Otherwise, you would have to do the update manually and make sure you refresh your token before the expiration date to maintain the connection.

Rate limit

  • There is a limit of 200 requests per minute for POST requests on every /api/v2 endpoints
  • There is a limit of 100 request per minute for POST requests on every /api/v1 endpoints