• 📒 Table of Contents

Overview

In this guide, you will learn how to:

• Request authorization from companies that you would like to manage on their behalf.
• Create your first company and obtain a company-scoped access token at the same time.
• Create your first employment for the same company.

Before you get started

Before you get started, ensure that you:

• Received your CLIENT_ID and CLIENT_SECRET keys from Remote and stored them securely.
• Can reach Remote's servers and fully authenticate using your credentials, according to the Authentication instructions we’ve provided.

Although not necessary, getting yourself familiarized with the Auth & Authorization page will help you throughout this guide.

Obtaining your Client Credentials Access Token

Referred to as “Client Credentials” or client_credentials, this type of access token grants access for your integration to act on behalf of itself and is obtained using the “Client Credentials Grant” type in OAuth 2.0. You will use this token to create your first company.

Obtaining your client_credentials access token does not require company consent because this access token does not let you act on behalf of another company.

Requesting an ACCESS_TOKEN

<aside> ℹ️ When you’re ready to release your integration, replace the domain with https://gateway.remote.com

You can find the API documentation for the /auth/oauth2/token endpoint here.

</aside>

To request an ACCESS_TOKEN, you need to send a POST request to our Authorization Servers according to the following items:

• Send a POST request to https://gateway.remote-sandbox.com/auth/oauth2/token
• Include the authorization header with basic authentication encoded with Base64:
  • Generate the Base64 with both credentials separated by a colon (:) as shown here — <client_id>:<client_secret>
  • Use the header Authorization: Basic <client_id_and_client_secret_encoded_in_base64>
• Include the Content-Type: application/x-www-form-urlencoded header in the request
• In the payload, you need to fill the grant type:
  • grant_type filled with client_credentials — it's a constant value

Assuming your CLIENT_ID=your_client_id and CLIENT_SECRET=your_client_secret, an example of what your request should look like is shown below.

$ echo -n "your_client_id:your_client_secret" | base64
eW91cl9jbGllbnRfaWQ6eW91cl9jbGllbnRfc2VjcmV0

$ curl --location \\
       --request POST '<https://gateway.remote-sandbox.com/auth/oauth2/token>' \\
       --header 'Authorization: Basic eW91cl9jbGllbnRfaWQ6eW91cl9jbGllbnRfc2VjcmV0' \\
       --header 'Content-Type: application/x-www-form-urlencoded' \\
       --data-urlencode 'grant_type=client_credentials'

The response to this request should look like the following JSON:

{
  "access_token": "eyJraWQiOiIrRHF3Y1A4TU80bEMrN1NxSVQxSVcHHL6LLZH0o_xWvoUG...",
  "expires_in": 3600,
  "token_type":"Bearer"
}

This means that the access_token of the type Bearer will expire in 3600 seconds after the time of the request.

<aside> 💡 The access token will be valid for 3600 seconds (one hour), so we recommend that the caller fetch a new access token before the current one expires (e.g. every 55 minutes). Please note that there is no limit to the number of access tokens that can be used at the same time.

</aside>

If you have any questions regarding the “Client Credentials Flow,” you can view the FAQ on this page.

Creating your first company

If you want to act on behalf of a company that already exists, you would follow the Authorization Code Flow to request consent from an admin of that company. But what about when your integration is the one creating the company?

Eligible Remote API partners are allowed to create the company and get the company’s “consent” in a single request. That means you can get the access token for the company at the same time you create the company, eliminating your need to go through the Authorization Code Flow to obtain consent after creating the company through the Remote API.

How do you know if you’re an eligible Remote API partner?