***

title: Authentication
description: 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:

<CardGroup cols={2}>
  <Card title="API Tokens" icon="fa-light fa-key" iconSize={8} href="#api-tokens">
    Simple token-based authentication for server-to-server integrations (covered on this page)
  </Card>

  <Card title="OAuth2" icon="fa-light fa-lock" iconSize={8} href="/api/oauth">
    Industry-standard protocol for user-authorized app access (see OAuth2 page)
  </Card>
</CardGroup>

This page covers **API Tokens**. For OAuth2 authentication, see the [OAuth2 documentation](/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

<Steps>
  <Step title="Navigate to Developer Center">
    Go to **More** → **Developer** in your Deel dashboard
  </Step>

  <Step title="Access the Tokens tab">
    Click on **Access Tokens** tab
  </Step>

  <Step title="Create new token">
    Click **Generate new token**
  </Step>

  <Step title="Choose token type">
    Select the appropriate token type for your use case:

    <Tabs>
      <Tab title="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
      </Tab>

      <Tab title="Personal Token">
        **Personal Token**: Limited to the user's accessible resources

        Use this for:

        * Contract creation
        * SSO integrations
        * User-specific operations
      </Tab>
    </Tabs>
  </Step>

  <Step title="Select scopes">
    Choose the scopes (permissions) your token needs. Scopes are listed in the API reference.
  </Step>

  <Step title="Configure sensitive data access">
    Customize what sensitive data the token can access
  </Step>

  <Step title="Generate and save">
    Review your settings and click **Generate**

    <Warning>
      **Important**: Copy and securely store the token immediately. You cannot retrieve it again after this screen.
    </Warning>
  </Step>
</Steps>

### Using API Tokens

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

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

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

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

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

  ```python Python
  import requests
  import os

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

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

  ```go Go
  package main

  import (
      "net/http"
      "os"
  )

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

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

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

### Best Practices for API Tokens

<AccordionGroup>
  <Accordion title="Security" icon="shield">
    * **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
  </Accordion>

  <Accordion title="Scope Selection" icon="sliders">
    * **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
  </Accordion>

  <Accordion title="Token Rotation" icon="rotate">
    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
  </Accordion>
</AccordionGroup>

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

<Note>
  **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).
</Note>

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

<AccordionGroup>
  <Accordion title="401 Unauthorized Error" icon="triangle-exclamation">
    **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
  </Accordion>

  <Accordion title="403 Forbidden Error" icon="ban">
    **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
  </Accordion>

  <Accordion title="Token Expired" icon="clock">
    **Solution:**

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

  <Accordion title="HTTPS Required Error" icon="lock">
    **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`
  </Accordion>
</AccordionGroup>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Secure Storage" icon="triangle-exclamation">
    Store credentials in environment variables or secure vaults, never in code
  </Accordion>

  <Accordion title="Regular Rotation">
    Rotate tokens quarterly or when team members leave
  </Accordion>

  <Accordion title="Minimal Scopes" icon="filter">
    Request only the scopes your application absolutely needs
  </Accordion>

  <Accordion title="Monitor Usage" icon="chart-line">
    Log and monitor API calls to detect unusual patterns
  </Accordion>

  <Accordion title="HTTPS Only" icon="lock">
    Never make API requests over unencrypted connections
  </Accordion>

  <Accordion title="Revoke Quickly" icon="ban">
    Immediately revoke tokens if compromise is suspected
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="OAuth2" icon="fa-light lock" href="/api/oauth">
    Learn about OAuth2 authentication for third-party apps
  </Card>

  <Card title="Rate Limits" icon="fa-light gauge" href="/api/rate-limits">
    Understand API rate limits and best practices
  </Card>

  <Card title="Webhooks" icon="fa-light webhook" href="/api/webhooks/quickstart">
    Set up webhooks for real-time notifications
  </Card>

  <Card title="Try in Sandbox" icon="fa-light flask" href="/api/sandbox">
    Test authentication in the sandbox environment
  </Card>
</CardGroup>