OAuth2

What is OAuth2?

OAuth 2.0 is the industry-standard protocol for authorization. It allows your app to access specific data in user accounts with explicit user consent, without requiring users to share their passwords.

• Secure Access: Users authorize without sharing passwords
• Granular Permissions: Request only the scopes your app needs
• Token-Based: Access and refresh tokens for secure API calls
• User Consent: Explicit approval for each permission

How OAuth2 Works

OAuth2 uses the authorization code grant flow:

The flow ensures secure, controlled access by:

1. Requiring explicit user consent
2. Using temporary authorization codes
3. Providing time-limited access tokens
4. Supporting granular permissions through scopes

Creating an OAuth2 App

OAuth2 Flow Implementation

Step 1: Request Permissions

Redirect users to Deel’s authorization endpoint with the required parameters:

https://app.deel.com/oauth2/authorize?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope={SCOPES}&state={STATE}

Required Parameters:

Example URL:

$
https://app.deel.com/oauth2/authorize?client_id=abc123&redirect_uri=https://yourapp.com/callback&scope=contracts:read%20contracts:write&state=random_string_xyz

1
// Generate authorization URL
2
const authUrl = new URL('https://app.deel.com/oauth2/authorize');
3
authUrl.searchParams.append('client_id', process.env.CLIENT_ID);
4
authUrl.searchParams.append('redirect_uri', 'https://yourapp.com/callback');
5
authUrl.searchParams.append('scope', 'contracts:read contracts:write');
6
authUrl.searchParams.append('state', generateRandomState()); // Implement CSRF protection
7
8
// Redirect user
9
res.redirect(authUrl.toString());

Step 2: User Authorizes

The user sees a consent screen showing:

• Your app name and logo
• What permissions (scopes) you’re requesting
• Option to approve or deny

When they approve, they’re redirected to your redirect_uri with an authorization code:

https://yourapp.com/callback?code=AUTH_CODE&state=random_string_xyz

Step 3: Exchange Code for Access Token

Exchange the authorization code for an access token by making a POST request:

$
curl -X POST 'https://app.deel.com/oauth2/tokens' \
>
  -H 'Authorization: Basic BASE64_ENCODED_CREDENTIALS' \
>
  -H 'Content-Type: application/x-www-form-urlencoded' \
>
  -d 'grant_type=authorization_code' \
>
  -d 'code=AUTH_CODE' \
>
  -d 'redirect_uri=https://yourapp.com/callback'

Authentication:

• Use HTTP Basic authentication
• Encode your credentials: base64(client_id:client_secret)

Example encoding:

$
echo -n "client_id:client_secret" | base64

1
const axios = require('axios');
2
3
// Encode credentials
4
const credentials = Buffer.from(
5
  `${process.env.CLIENT_ID}:${process.env.CLIENT_SECRET}`
6
).toString('base64');
7
8
// Exchange code for token
9
const response = await axios.post(
10
  'https://app.deel.com/oauth2/tokens',
11
  new URLSearchParams({
12
    grant_type: 'authorization_code',
13
    code: authCode,
14
    redirect_uri: 'https://yourapp.com/callback'
15
  }),
16
  {
17
    headers: {
18
      'Authorization': `Basic ${credentials}`,
19
      'Content-Type': 'application/x-www-form-urlencoded'
20
    }
21
  }
22
);
23
24
const { access_token, refresh_token, expires_in } = response.data;

Response:

1
{
2
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
3
  "token_type": "Bearer",
4
  "expires_in": 2592000,
5
  "refresh_token": "def502000a2b3c4d5e6f...",
6
  "scope": "contracts:read contracts:write"
7
}

Step 4: Make Authenticated Requests

Use the access token to make API requests. OAuth2 requests require two headers:

$
curl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \
>
  -H 'Authorization: Bearer ACCESS_TOKEN' \
>
  -H 'x-client-id: CLIENT_ID'

1
const axios = require('axios');
2
3
const deelAPI = axios.create({
4
  baseURL: 'https://api.letsdeel.com/rest/v2',
5
  headers: {
6
    'Authorization': `Bearer ${accessToken}`,
7
    'x-client-id': process.env.CLIENT_ID
8
  }
9
});
10
11
// Make authenticated request
12
const contracts = await deelAPI.get('/contracts');
13
console.log(contracts.data);

Token Rotation

Access tokens expire after 30 days. Refresh them before expiration to maintain uninterrupted access.

Refreshing Access Tokens

Make a POST request with your refresh token:

$
curl -X POST 'https://app.deel.com/oauth2/tokens' \
>
  -H 'Authorization: Basic BASE64_ENCODED_CREDENTIALS' \
>
  -H 'Content-Type: application/x-www-form-urlencoded' \
>
  -d 'grant_type=refresh_token' \
>
  -d 'refresh_token=REFRESH_TOKEN' \
>
  -d 'redirect_uri=https://yourapp.com/callback'

1
const axios = require('axios');
2
3
async function refreshAccessToken(refreshToken) {
4
  const credentials = Buffer.from(
5
    `${process.env.CLIENT_ID}:${process.env.CLIENT_SECRET}`
6
  ).toString('base64');
7
8
  const response = await axios.post(
9
    'https://app.deel.com/oauth2/tokens',
10
    new URLSearchParams({
11
      grant_type: 'refresh_token',
12
      refresh_token: refreshToken,
13
      redirect_uri: 'https://yourapp.com/callback'
14
    }),
15
    {
16
      headers: {
17
        'Authorization': `Basic ${credentials}`,
18
        'Content-Type': 'application/x-www-form-urlencoded'
19
      }
20
    }
21
  );
22
23
  return response.data; // Contains new access_token and refresh_token
24
}

Response includes:

• New access token (valid for another 30 days)
• Token expiration time (2,592,000 seconds)
• New refresh token (use this for next refresh)
• Token type (Bearer)
• Authorized scopes

Best Practices for Token Rotation

Scopes Reference

Request only the scopes your application needs. Each API endpoint specifies which scopes are required - check the API Reference for details.

Common scope combinations:

Recommended App Types by Use Case

Troubleshooting

Security Best Practices

Next Steps