Authentication | Deel. PayAndBill API Documentation

The Deel. PayAndBill API uses OAuth 2.0 Authorization Code flow for authentication. All API endpoints (except the authentication endpoints themselves) require a valid Bearer token.

OAuth 2.0 Flow

Request Authorization

Redirect the user to the authorization endpoint to obtain an authorization code.

GET https://api.astutepayroll.com/openapi/oauthv1/authorize
  ?responseType=code
  &clientId=YOUR_CLIENT_ID
  &redirectUri=https://yourapp.com/callback
  &scope=read write
  &state=RANDOM_STATE_VALUE

Parameter	Required	Description
`responseType`	Yes	Must be set to `code`.
`clientId`	Yes	Your application’s client ID.
`redirectUri`	Yes	The URI where the user will be redirected after authorization. Must match the registered URI.
`scope`	Yes	A space-separated or comma-separated list of requested permissions (e.g., `read write` or `read,write`).
`state`	Yes	A random string to prevent CSRF attacks. Verify this value on callback.

Exchange Code for Token

After the user authorizes your application, they will be redirected to your redirectUri with a code parameter. Exchange this code for an access token:

curl -X POST https://api.astutepayroll.com/openapi/oauthv1/token \
  -H "Content-Type: application/json" \
  -d '{
    "code": "AUTHORIZATION_CODE",
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "redirectUri": "https://yourapp.com/callback",
    "grantType": "authorization_code"
  }'

Use the Access Token

Include the access token in the Authorization header of all API requests:

curl -X GET https://api.astutepayroll.com/employees/list \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Refreshing Tokens

When your access token expires, use the refresh token to obtain a new one without requiring the user to re-authorize:

curl -X POST https://api.astutepayroll.com/openapi/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "redirectUri": "https://yourapp.com/callback",
    "grantType": "authorization_code",
    "refreshToken": "YOUR_REFRESH_TOKEN"
  }'

Required Headers

All authenticated requests must include the following headers:

Header	Value	Description
`Authorization`	`Bearer <token>`	Your OAuth access token.
`Accept`	`application/json`	Expected response format.
`vnd.a1.tenant-id`	`<tenant-id>`	Tenant identifier for multi-tenant environments.