Overview

This specification outlines the APIs required for issuing an access token on behalf of a user for a server-to-server request. The user can be an employee or a manager.

Step 1 — Generating and signing a JWT Token

The partner needs to generate a JWT Token and sign it with their client_secret The JWT needs to have the following fields:

Field	Description
iss	The token issuer. this is the client_id of the partner.
sub	The subject of the token. This should contain the user_id in this format `urn:remote-api:company-manager:user:<user-id>` or employment_id in this format `urn:remote-api:employee:emplomyent:<employment-id>` .
aud	The audience. This will vary depending on the environment and URL must match the requested server. Possible values are: https://gateway.partners.remote-sandbox.com/auth https://gateway.remote-sandbox.com/auth https://gateway.remote.com/auth
exp	The expiration time. By the time our Auth Server receives the request, the exp timestamp needs to be up to 10 minutes in the future. The server will reject timestamps in the past or when it is greater than 10 minutes in the future. For security, we recommend partners to expire their tokens in less than 10 minutes.
scope	Partners can define specific scopes for the token they are generating. This is done by specifying which permissions should be granted to the token, as shown in the example below: scope = "offboarding:write timeoff:read employment:read" If no scope is specified, the token will be granted all available scopes by default. However, we strongly encourage you to implement specific scopes as soon as possible, as this default behavior will be deprecated.

Example of a JWT Token content

{
	"iss": "8ab0eb8c2b4311f09ca9b7cfd4ed3c38", // format might change
	"sub": "urn:remote-api:employee:emplomyent:99bf04d8-2b43-11f0-8cf4-d38ed3edc31e", 
	"aud": "https://gateway.partners.remote-sandbox.com/auth",
	"exp": 1746571356 // expires at 2025-05-06 22:42:36Z,
	"scope": "timeoff:read"
}

Example of JWT Token generation in Python

import jwt
from datetime import datetime, timedelta

# Partner client_secret
client_secret = '704049bf85ae49fdbc9e791b8f51dfe9'

payload = {
		'iss': '8ab0eb8c2b4311f09ca9b7cfd4ed3c38',
		'sub': 'urn:remote-api:company-manager:user:8f924bdc-4169-49c8-b09b-552761965b78',
		'aud': 'https://gateway.partners.remote-sandbox.com/auth',
    'exp': datetime.utcnow() + timedelta(minutes=10), # Token expiration time
    'scope': 'offboarding:write timeoff:read employment:read'
}

try:
    encoded_jwt = jwt.encode(payload, client_secret, algorithm='HS256')
    print("Generated JWT:")
    print(encoded_jwt)
except Exception as e:
    print(f"Error generating JWT: {e}")

Step 2 — Exchanging partner's JWT Token by an API Access Token

Now that you have generated a JWT Token, you can exchange it for an API Access Token.

Request to Remote Token endpoint

POST /auth/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<jwt_token>

Expected response

{
    "access_token": "eyJraWQiOiJSUmFJ[...].eyJzdWIiOiI0dn[...].vfQ9cAl[...]",
    "expires_in": 3600,
    "token_type": "Bearer"
}

You'll use the access_token content in the Authorization header just like any other request.

Doing a request

POST /v1/employee/offboardings HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{...}

Diagrams

this diagram explains the interaction between the SDK and the BE for the token generation:

and this diagram explain in details the backend flow:

Technical direction

Use the OAuth 2.0 JWT Bearer Assertion flow for all server-to-server calls, always binding the token to the real actor in Remote.

1) Replace refresh-token with per-actor assertions for system automations

When to use: background jobs and API calls that currently use refresh tokens. This is useful if Partner wants to maintain a single authentication method for all requests; otherwise, it's not necessary.
How: map the Partner admin to their Remote user_id, then issue a JWT with

sub = urn:remote-api:company-manager:user:<company_owner_remote_user_id>

scope = <scopes_needed_for_the_action>

Exchange it for an access token, and then call the APIs as usual.
Why: aligns permissions and audit trails with a specific Remote user; mirrors the current "owner-level" access that refresh tokens provide, while improving traceability and offering the ability to limit the token's scope for specific actions.

2) Offboarding initiated by admins in Partner platform

When to use: an admin performs an offboarding in Partner platform.
How: map the Partner admin to their Remote user_id, then issue a JWT with

sub = urn:remote-api:company-manager:user:<requesting_admin_remote_user_id>

scope = offboarding:write timeoff:read employment:read

Exchange for an access token and submit the offboarding request.
Benefits: Remote's audit log will attribute the action to the actual admin, allowing Remote teams to follow up with the right person. Additionally, the user can be restricted to only perform the specific actions needed for the offboarding process.
Operational notes: Partner should maintain a reliable mapping between Partner users and Remote user_ids. As a security measure, Remote strongly recommends using scopes to restrict the generated token so it can only access offboarding-related endpoints.
Partners don't need to manage tokens for each user; they can simply request new tokens as needed.

3) Employee time-off requests

When to use: an employee submits time off in Partner platform
How: reuse the same assertion flow.

sub = urn:remote-api:employee:employment:<requesting_employee_remote_employment_id

scope = timeoff:write
Outcome: consistent auth, clean auditability, and uniform token handling across use cases.