Essentials

Authentication

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

2

Access the Tokens tab

Click on Access Tokens tab

3

Create new token

Click Generate new token

4

Choose token type

Select the appropriate token type for your use case:

Organization Token: Provides access to all organization resources

Use this for:

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

Select scopes

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

6

Configure sensitive data access

Customize what sensitive data the token can access

7

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'
1const axios = require('axios');
2
3const 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
11const response = await deelAPI.get('/contracts');

Best Practices for API Tokens

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

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

ScenarioRecommended Method
Server-to-server integrationAPI Tokens
Internal automation scriptsAPI Tokens
Third-party app requiring user consentOAuth2 (see OAuth2 docs)
Multi-tenant SaaS applicationOAuth2 (see OAuth2 docs)
Accessing your own organization’s dataAPI Tokens
App Store published applicationsOAuth2 (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

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

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

Solution:

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

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

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

Rotate tokens quarterly or when team members leave

Request only the scopes your application absolutely needs

Log and monitor API calls to detect unusual patterns

Never make API requests over unencrypted connections

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