Getting started with Factorial - Authentication

❗️

V1.0 DEPRECATED

The v1.0 version has been deprecated.

It will be supported until April 1st 2025. Afterwards, it will be removed

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

API Keys

❗️

DISCLAIMER

API Key usage for marketplace integrations will be deprecated at the end of 2024. New marketplace integrations must use OAuth company token for company-wide access

Internal company integrations will still supported

API Keys 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.

API keys have TOTAL ACCESS to everything and never expire. It's the creator's responsibility to generate them and store them securely.

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

For example

curl --location --request GET 'Base URL' --header 'x-api-key: YOUR-API-KEY'

• Base URL: You can get these endpoints from our API Reference

📘

API KEY Generation

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

❗️

DISCLAIMER

API Key management requires 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 operations are not linked to any user in particular.

OAuth 2.0

📘

Use

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

OAuth2 is available for authenticating to the public API and making requests via third parties on behalf of a user or a company. In case of user tokens, all actions are authored on behalf of the user that creates the token. This means, is to be used mainly to submit actions the actual user is performing on an alternative interface or for. On the other hand, in case of company tokens, all actions are authored on behalf of the user's company. This kind of token is mainly used for sharing data without the user interaction.

To use OAuth 2, the user needs to meet certain requirements:

• The user needs to be an employee inside Factorial interface
• The user needs to be on a permission group with the correspondent access to Factorial information. For example, if the user shouldn't see contracts of other employees, their set of permissions should reflect this.
• Only admin users can access OAuth 2 repository and change the configuration

Steps to set up your OAuth 2

1. Create a new OAuth application and follow the creation process.

2. Generate the OAuth 2 Authorization Code in order to generate an OAuth2 Token.

3. You will request an Access token

4. Refresh an access token (in case you need it)

Useful information about our API

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.

Sandbox development
In case you need a Sandbox development, contact your Account Manager, who will provide a Demo environment in Factorial for testing purposes.
More about Sandbox, here

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