Getting Started with Factorial API

Learn and start using Factorial's API by following all the foot steps.

• Getting Started with Factorial

• Create a new Oauth application

• Request an Authorization Code

• Request an Access Token

• Refreshing an Access Token

• Sandbox Development

---

Getting Started with Factorial

 

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:

1. Create an Oauth Application
2. Request an authorization code for the application
3. Request an access token with the provided authorization code
4. 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

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.

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:

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:

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!

---

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.

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.

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}

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.

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.