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
andCLIENT_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.
-
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.
Updated 15 days ago