Authorization for Partners

The Remote API uses the OAuth 2 protocol for authorization. This means every request needs a valid access token for it to succeed. Access is valid for 3600 seconds (one hour).

There are some terms that appear across all the authorization documentation. Check the quick glossary below for term definitions.

Quick Glossary

This quick glossary is a guide for understanding who and where an operation must take place.

User or Company Admin: This refers to a Remote customer who is signed in as the Admin role in Remote. In OAuth terms, they are the Resource Owner.
Client Application: This is the piece of software a party uses to interact with the Remote API.
Remote UI: This term refers to the Remote platform.
Authorization Server: This is a set of endpoints used for authenticating and authorizing requests to the Remote API.
Remote API: The set of endpoints a Client Application can use to manage authorized companies. This is the Resource Server.
Client Registration: The process a Remote API Partner goes through to correctly configure the integration with Remote.

Requesting an Access Token

Currently, there are two ways to request an access token. They are designed for specific use cases ensuring the security of the transactions.

Client Credentials Flow: In this flow, the Remote API Partner is able to authenticate using their CLIENT_ID and CLIENT_SECRET. All actions are made on behalf of the Remote API Partner.
Refresh Token Flow: In this flow, a Client Application can exchange a valid refresh token for an access_token.

ℹ️ The **Refresh Token flow is important** because the access token returned at the end of the Authorization Code flow expires in one hour. After expiration, issuing a new access token through the Refresh Token Flow is required.

Client Credentials Flow

In the Client Credentials Flow, a Client Application fetches an access_token using the CLIENT_ID and CLIENT_SECRET. It allows for the creation of a new company and managing any other company that has granted consent through the Authorization Code Flow.

🖇️ ➡️ More detailed instructions for using this flow are available on the Client Credentials Flow page.

Refresh Token Flow

In the Refresh Token Flow, a Client Application exchanges the refresh_token obtained at the end of one of the two flows described below. It is possible to obtain refresh_tokens from these two different scenarios:

Connecting to an existing Remote Company: Used if the Remote API Partner wants to create new employments, time-offs, or update company attributes — for instance, a Remote Company Admin needs to give consent first. In this flow, an existing Remote Company grants the consent to the Remote API Partner for acting on behalf of the user who authorized the integration. Any Company Admin can give consent.

🖇️ ➡️ Learn how to connect to an existing company with the Authorization Code Flow.
Creating a new Remote Company: When creating the Remote Company, the Remote API Partner can ask for the OAuth authorization to be executed as well. The proper tokens are returned in the company creation payload, which enables fetching access_tokens on behalf of the Company Admin user. Learn how to create a new company with consent.

After going through either of these two flows, you can exchange the refresh_token for a valid access_token at any time following the Refresh Token Flow.