Authentication

Overview

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

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

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

This page covers API Tokens. For OAuth2 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

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

Personal Token

Organization Token: Provides access to all organization resources

Use this for:

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

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:

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

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

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)
Multi-tenant SaaS application	OAuth2 (see OAuth2 docs)
Accessing your own organization’s data	API Tokens
App Store published applications	OAuth2 (see OAuth2 docs)

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.

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/v2

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

Learn about OAuth2 authentication for third-party apps

Rate Limits

Understand API rate limits and best practices

Webhooks

Set up webhooks for real-time notifications

Try in Sandbox

Test authentication in the sandbox environment

Overview

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

API Tokens

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

OAuth2

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

This page covers API Tokens. For OAuth2 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

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

Personal Token

Organization Token: Provides access to all organization resources

Use this for:

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

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:

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

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

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)
Multi-tenant SaaS application	OAuth2 (see OAuth2 docs)
Accessing your own organization’s data	API Tokens
App Store published applications	OAuth2 (see OAuth2 docs)

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.

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/v2

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

Learn about OAuth2 authentication for third-party apps

Rate Limits

Understand API rate limits and best practices

Webhooks

Set up webhooks for real-time notifications

Try in Sandbox

Test authentication in the sandbox environment

$	curl -X GET 'https://api.letsdeel.com/rest/v2/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/v2',
5	headers: {
6	'Authorization': `Bearer ${process.env.DEEL_API_TOKEN}`
7	}
8	});
9
10	// Make authenticated request
11	const response = await deelAPI.get('/contracts');