> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.a1.uk.astutepayroll.in/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.a1.uk.astutepayroll.in/_mcp/server.

# Authentication

> Learn how to authenticate with the Deel. PayAndBill API using OAuth 2.0

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:

```bash
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:

```bash
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:

```bash
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. |