Sandbox development

A sandbox/demo environment, it's 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 (tell them a demo 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
• Api Key
• 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.factorial.dev/oauth/applications

Create your credentials

Remember to place your redirect URI

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.

Once you have authorized the application, you will have all your data available

Data available

Now you are ready to create your token. You can follow these steps in the Create an access token section (remember to change the URL to https://api.demo.factorial.dev/)

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.factorial.dev/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.factorial.dev

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.factorial.dev/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.