> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server.

# Authentication

> Learn how to authenticate your API requests with API tokens or OAuth2

## Overview

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

#### [API tokens](#api-tokens)

Simple token-based authentication for server-to-server integrations (covered on this page)

#### [OAuth2](/api/oauth)

Industry-standard protocol for user-authorized app access (see OAuth2 page)

This page covers **API tokens**. For OAuth2 authentication, see the [OAuth2 documentation](/oauth).

## 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.

| Token type         | Represents              | How to obtain                                                                                                          | Use it for                                                                                                                                                       |
| ------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Organization token | The entire organization | Developer Center (dashboard)                                                                                           | Server-to-server integrations: contracts, payroll, invoices, SCIM                                                                                                |
| Personal token     | A single user (you)     | Developer Center (dashboard)                                                                                           | Contract creation, SSO integrations, user-scoped actions                                                                                                         |
| Worker API token   | A single EOR worker     | [Create worker access token](/api/reference/endpoints/worker-session/create-worker-access-token-v-2026-01-01) endpoint | Embedded flows where the worker acts on their own data — for example, [worker-initiated resignation](/api/employer-of-record/eor-offboarding/worker-resignation) |

For OAuth2-based authentication, see the [OAuth2 documentation](/api/oauth).

## 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

#### Navigate to Developer Center

Go to **More** → **Developer** in your Deel dashboard

#### Access the Tokens tab

Click on **Access Tokens** tab

#### Create new token

Click **Generate new token**

#### Choose token type

Select the appropriate token type for your use case:

#### Organization token

**Organization token**: Provides access to all organization resources

Use this for:

* Reading contract data
* Managing timesheets
* Invoice adjustments
* Accounting data
* SCIM API access

#### Personal token

**Personal token**: Limited to the user's accessible resources

Use this for:

* Contract creation
* SSO integrations
* User-specific operations

#### Select scopes

Choose the scopes (permissions) your token needs. Scopes are listed in the API reference.

#### Configure sensitive data access

Customize what sensitive data the token can access

#### Generate and save

Review your settings and click **Generate**

**Important**: Copy and securely store the token immediately. You cannot retrieve it again after this screen.

### Using API tokens

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

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

**`Node.js`**

```javascript Node.js
const axios = require('axios');

const deelAPI = axios.create({
  baseURL: 'https://api.letsdeel.com/rest',
  headers: {
    'Authorization': `Bearer ${process.env.DEEL_API_TOKEN}`
  }
});

// Make authenticated request
const response = await deelAPI.get('/contracts');
```

**`Python`**

```python Python
import requests
import os

headers = {
    'Authorization': f'Bearer {os.getenv("DEEL_API_TOKEN")}'
}

response = requests.get(
    'https://api.letsdeel.com/rest/contracts',
    headers=headers
)
```

**`Go`**

```go Go
package main

import (
    "net/http"
    "os"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.letsdeel.com/rest/contracts", nil)

    req.Header.Add("Authorization", "Bearer " + os.Getenv("DEEL_API_TOKEN"))

    resp, err := client.Do(req)
    // Handle response...
}
```

### Best practices for API tokens

#### Security

* **Never commit tokens** to version control
* **Use environment variables** to store tokens
* **Rotate tokens regularly** to minimize security risks
* **Use HTTPS only** for all API requests
* **Delete unused tokens** immediately

#### Scope selection

* **Use the least privilege principle**: Only grant the minimum scopes needed
* **Separate tokens by function**: Create different tokens for different integrations
* **Organization vs personal**: Choose based on your access requirements

#### Token rotation

API credentials should be changed regularly. Employees leave, API credentials can be accidentally committed to version control, and security flaws can be discovered.

**When to rotate:**

* Proactively on a regular schedule (quarterly recommended)
* Immediately if potential compromise is suspected
* When team members with access leave

## 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](/api/reference/endpoints/worker-session/create-worker-access-token-v-2026-01-01) endpoint using a client API token. The response returns a Bearer token scoped to a single worker.

This endpoint is only available to organizations with the Embedded partnership model enabled. Contact your Deel representative to enable it. See [Getting started](/api/embedded/getting-started#prerequisites) for the full Embedded prerequisites.

### Using a worker API token

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

```bash
curl -X GET 'https://api.letsdeel.com/rest/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/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

| Scenario                                             | Token type       |
| ---------------------------------------------------- | ---------------- |
| Worker submits their own resignation                 | Worker API token |
| Worker previews their resignation letter             | Worker API token |
| Worker views their pending offboarding tasks         | Worker API token |
| Client initiates a resignation on behalf of a worker | Client API token |
| Client reviews PTO during resignation                | Client API token |
| Client terminates a worker                           | Client API token |

For flows that combine both token types, see the [EOR offboarding](/api/employer-of-record/eor-offboarding) guide.

## When to use API tokens vs OAuth2

| Scenario                               | Recommended method                     |
| -------------------------------------- | -------------------------------------- |
| Server-to-server integration           | **API tokens**                         |
| Internal automation scripts            | **API tokens**                         |
| Third-party app requiring user consent | **OAuth2** ([see OAuth2 docs](/oauth)) |
| Multi-tenant SaaS application          | **OAuth2** ([see OAuth2 docs](/oauth)) |
| Accessing your own organization's data | **API tokens**                         |
| App Store published applications       | **OAuth2** ([see OAuth2 docs](/oauth)) |

## Scopes

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

**Least privilege principle**: Only grant the minimum scopes necessary for your use case. Each API endpoint lists its required scopes in the [API reference](/reference).

**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

#### 401 Unauthorized error

**Common causes:**

* Invalid or expired token
* Missing `Authorization` header
* Token doesn't have required scopes

**Solutions:**

* Verify token is correct and not expired
* Check header formatting: `Authorization: Bearer TOKEN`
* Ensure token has necessary scopes
* Generate a new token if needed

#### 403 Forbidden error

**Common causes:**

* Token lacks required scopes for the endpoint
* Attempting to access resources outside token's permissions

**Solutions:**

* Review the scopes assigned to your token
* Generate a new token with appropriate scopes

#### Token expired

**Solution:**

* Generate a new token in Developer Center
* Update your application with the new token
* Consider setting up a rotation schedule

#### HTTPS required error

**Cause:**

* Attempting to make requests over HTTP

**Solution:**

* All API requests must use HTTPS
* Update your base URL to `https://api.letsdeel.com/rest`

## Security best practices

#### Secure storage

Store credentials in environment variables or secure vaults, never in code

#### Regular rotation

Rotate tokens quarterly or when team members leave

#### Minimal scopes

Request only the scopes your application absolutely needs

#### Monitor usage

Log and monitor API calls to detect unusual patterns

#### HTTPS only

Never make API requests over unencrypted connections

#### Revoke quickly

Immediately revoke tokens if compromise is suspected

## Next steps

#### [OAuth2](/api/oauth)

Learn about OAuth2 authentication for third-party apps

#### [Rate limits](/api/rate-limits)

Understand API rate limits and best practices

#### [Webhooks](/api/webhooks/quickstart)

Set up webhooks for real-time notifications

#### [Try in sandbox](/api/sandbox)

Test authentication in the sandbox environment