Learn and start using Factorial's API by following all the foot steps.
Getting Started with Factorial
📘Sign up to Factorial
First things first, to start using Factorial's API you'll need a Factorial account with administrator permissions to create an Oauth Application. So head over to the sign up page if you haven't done so already.
NOTE: After an Oauth Application is created, NON-ADMIN users can use the credentials to request Oauth Tokens
Authorization & Authentication
Factorial's API leverages OAuth2 and the Authorization Code Flow for authentication and authorization of users using the API. That means that you'll have to follow a simple series of security steps in order to use Factorial's API.
These steps can be broken down to:
- Create an Oauth Application
- Request an authorization code for the application
- Request an access token with the provided authorization code
- You can now make requests to Factorial's API!
We are gonna go through each step in the following sections.
Create a New Oauth Application
📘Administrator Permissions required
In order to perform the following steps, you are gonna need to be logged in Factorial with an administrator account. Administrator permissions can be granted to multiple users from the Company Settings section.
In order to create an OAuth application, head over to your personal repository of OAuth applications, click on New application and follow the creation process.
If you get lost at any point, remember you can always navigate to your repository of OAuth applications at any time.
Let's take a closer look at the most important steps from the creation process.
Redirect URI
The redirect URI the user will be redirected once it has granted permissions to your application to use information from Factorial's API.
🚧Note about the Redirect URI
Kindly note that the Redirect URI in the Oauth Application dashboard MUST correspond with the Redirect URI in the body of your request for a new access token.
Confidentiality
Indicates whether you can keep the client secret secure and inaccessible to any malicious actor.
Web and mobile applications are not considered secure as a malicious actors could use debuggers to discover the client secret. Server applications with secure firewalls and protected access are considered secure.
Permissions
The Factorial API enforces the same permissions at the user level then 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. The API reference includes notes detailing the permissions schema of each endpoint.
Request an Authorisation Code
Once you have registered your Oauth application in Factorial you will be able to let your users grant your integration access to Factorial's API. In order to do that, you will need to redirect users of your integration to the following URL:
🚧Note
Non-admin users can perform this action, as long as they have the Oauth Application credentials
Fetching your Authorization Code via the Dashboard
If you need an authorization token and you don't have a full oauth flow setup in your application code, consider using the authorize button in the oauth applications dashboard. It may be quicker for your use case, to retrieve your authorization code. This is particularly useful in cases of integrations with a single user like an external API.
Fetching your Authorisation code in your Application code
https://api.factorialhr.com/oauth/authorize?client_id=&redirect_uri=&response_type=code&scope=read,write
All the information required to build this URL is available in your OAuth application page, which you can access from the repository of Oauth applications.
Once access is granted and the authorization code has been displayed to the user. Your integration is in condition to request its first access token.
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>'
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" }
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>.
Now that you are authorized and authenticated to use Factorial's API, you might wanna check out our API reference. Happy hacking!
❗️Access token expiration
All access tokens are valid for a period of one week. 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.
Refreshing an Access Token
All access tokens are valid for a period of two hours. 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 Oauth Application credentials
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'
Sandbox Development
A sandbox/demo environment is available for testing integrations via public API calls. Developers can request provisioning with full access to a demo company where to test code before actually interacting with a production environment.
Contact your account manager or account executive to request this environment and get Oauth credentials for generating tokens.
🚧This environment is a demo and all information could be deleted at any moment.
Requirements
After provisioning you should receive the following items:
- Oauth Id
- Oauth Secret
- ApiKey
- Admin user credentials for the demo company
- Company name Integrations - {company name}
📘ApiKey
Currently the main supported authentication method is via OAuth2 on behalf of a User.
ApiKeys provide total access not associated to any user. This type of credentials may not be provided as their not fully available yet.
First Steps
Head over to the sandbox environment and login with the admin user credentials provisioned. Then, on the same browser tab open https://api.demo.factorialhr.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code to generate an Oauth2 code. Don't forget to replace CLIENT_ID with the Oauth Id provisioned. This will take you to a page where you authorise the Oauth2 protocol.
Take note of the code generated.
The next step is creating a user token, this can be done with a simple curl request.
curl -X POST 'https://api.demo.factorialhr.com/oauth/token' -d 'client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=CODE&grant_type=authorization_code&redirect_uri=urn:ietf:wg:oauth:2.0:oob'
Don't forget to replace CLIENT_ID with provisioned Oauth2 Id, CLIENT_SECRET with provisioned Oauth2 secret and the generated CODE!
Finally retrieve the token from the response and you're ready to make API calls.
📘Api Call Examples
Notice the examples in the next page have the production domain. Don't forget to change them to https://api.demo.factorialhr.com
First API Call
To test the token, a simple and easy request is retrieving the information of the token. To do so perform the following curl request. Don't forget to replace TOKEN.
curl https://api.demo.factorialhr.com/api/v1/me -H 'Authentication: Bearer TOKEN'
Conclusion
All endpoints available in this docs are also available in the sandbox environment. Don't forget to check the domain in your requests.