Authentication

You authenticate every Remote API request with a bearer token. This page shows which token to get and how to send it.

This is the prerequisite for everything else in these docs. Every guide links back here.

Who this is for

• Customers building their own integration to Remote.
• Partners shipping a product to many Remote companies.

Which token do you need?

Pick your path once, then follow it through the rest of the docs.

• Building your own integration to Remote: generate a Customer API token.
• Shipping a product to many Remote companies as a partner: use OAuth, set up with our partnerships team.

How auth works

Send the token in the Authorization header on every request:

Authorization: Bearer <token>

Customer API tokens carry a prefix that tells you the environment:

Partner OAuth access tokens do not use this prefix. For partners, the environment is set by the gateway host you call and the credentials you were provisioned. Whatever surface you use (API, MCP, SDK, or CLI), you always send the token as a bearer token in the Authorization header.

Gateway hosts and isolation

Sandbox and production are fully isolated. A ra_test_ token never works against production, and a ra_live_ token never works against sandbox. Data does not cross between them, so build and test in sandbox first. Public API paths are shown as /v1/....

Customer path: generate an API token

A company admin or owner generates a Customer API token in the Remote dashboard, under Company Settings, then Integrations & APIs. The token acts on behalf of the user who generated it.

Use a separate token per integration so you can scope and revoke each one independently.

For the full walkthrough, including how to revoke a token, see Obtaining access token.

Partner path: OAuth

Partners authenticate with OAuth 2.0. You receive a CLIENT_ID and CLIENT_SECRET, exchange them for access tokens, and act on behalf of the companies that grant you consent. Partner credentials are provisioned with our partnerships team, who confirm the scopes your product needs.

For the flows in full (client credentials, authorization code, and refresh token), see Authorization for Partners.

Scopes

Tokens carry scopes that limit what a request can do, for example timeoff:write or invoices:read. Request only the scopes your integration needs. If a call fails on permissions, check that the token carries the right scope.

Make an authenticated request

Set your token, then send it as the bearer token against the sandbox gateway:

export REMOTE_API_TOKEN=ra_test_...

curl https://gateway.remote-sandbox.com/v1/employments \
  -H "Authorization: Bearer $REMOTE_API_TOKEN"

Swap the host for https://gateway.remote.com and use a ra_live_ token when you go to production. For a full first-call walkthrough, see Your First API Call.

Good to know

• The prefix is the environment. ra_test_ is sandbox, ra_live_ is production. If a request is rejected, first check that the token prefix matches the host.
• Sandbox and production are isolated. Tokens are not portable between them.
• One token per integration. This keeps scopes tight and lets you revoke a single integration without breaking the others.
• Keep tokens secret. Treat them like passwords and never commit them to source control.

For AI agents

If you build with an AI coding assistant, point it at https://developer.remote.com/llms.txt for the full API reference as context, or install the remote-for-ai plugin, which ships a remote-api-auth skill that encodes these auth steps. See Build Integrations with AI to get started.

Give your assistant the token through the REMOTE_API_TOKEN environment variable and tell it to:

• Send Authorization: Bearer $REMOTE_API_TOKEN on every request.
• Match the token prefix (ra_test_ or ra_live_) to the gateway host.
• Never log or echo the token.

Next steps

• Your First API Call: make your first authenticated request and see a real response.
• Sandbox Quickstart: get a seeded sandbox company and a ra_test_ token to build against.