Authentication

Overview

All Deel API requests require authentication and must be made over HTTPS. Deel supports two authentication methods:

This page covers API tokens. For OAuth2 authentication, see the OAuth2 documentation.

Token types

Deel supports three API token variants. All are used as Bearer tokens in the Authorization header, but they differ in who they represent, how you obtain them, and which endpoints they can call.

For OAuth2-based authentication, see the OAuth2 documentation.

API tokens

API tokens provide a straightforward way to authenticate server-to-server API requests. Tokens are used as Bearer tokens in the Authorization header.

Generating an API token

Using API tokens

Include your token in the Authorization header as a Bearer token:

$
curl -X GET 'https://api.letsdeel.com/rest/contracts' \
>
  -H 'Authorization: Bearer YOUR-TOKEN-HERE'

1
const axios = require('axios');
2
3
const deelAPI = axios.create({
4
  baseURL: 'https://api.letsdeel.com/rest',
5
  headers: {
6
    'Authorization': `Bearer ${process.env.DEEL_API_TOKEN}`
7
  }
8
});
9
10
// Make authenticated request
11
const response = await deelAPI.get('/contracts');

Best practices for API tokens

Worker API tokens

A worker API token authenticates as a specific EOR worker rather than the client organization. Use it when an integration needs to act on behalf of an employee — for example, when the worker submits their own resignation or retrieves their own pending offboarding tasks.

Unlike organization and personal tokens, worker tokens are generated programmatically through the API, not the Developer Center dashboard.

Generating a worker API token

Call the Create worker access token endpoint using a client API token. The response returns a Bearer token scoped to a single worker.

Using a worker API token

Send the worker token in the Authorization header like any other Bearer token:

$
curl -X GET 'https://api.letsdeel.com/rest/v2/eor/workers/resignations' \
>
  -H 'Authorization: Bearer YOUR-WORKER-TOKEN'

Limitations

• Worker-scoped: A worker token can only act on the worker it was issued for.
• Limited endpoint coverage: Worker tokens authenticate only against worker-side endpoints (paths under /rest/v2/eor/workers/). Calling standard client endpoints with a worker token returns 403 Forbidden.
• Not interchangeable with client tokens: Standard client API tokens cannot call worker-side endpoints either. Flows that span both sides — such as client-initiated resignation — require both token types.

When to use a worker API token

For flows that combine both token types, see the EOR offboarding guide.

When to use API tokens vs OAuth2

Scopes

Scopes control granular access to different parts of the Deel API. When creating a token, you’ll select the scopes (permissions) it needs.

Common scope patterns:

• Read scopes: {resource}:read (e.g., contracts:read, people:read)
• Write scopes: {resource}:write (e.g., contracts:write, timesheets:write)

Check each endpoint’s documentation to see which scopes are required.

Troubleshooting

Security best practices

Next steps