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://<client>.pb.deel.com/openapi/oauth/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	Space-separated list of requested permissions.
`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://<client>.pb.deel.com/openapi/oauth/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://<client>.pb.deel.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://<client>.pb.deel.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.