> ## Documentation Index
> Fetch the complete documentation index at: https://jobticket-docs.ticket-plus.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Authorization

> How to authenticate with the JobTicket B2B API.

All JobTicket B2B API endpoints (except [Health Check](/v1/endpoint/health)) require authentication using **HTTP Basic Auth** with API key credentials issued from the Developer Portal.

## Getting your credentials

Credentials are issued per API key in the Developer Portal. Each key has a **username** and **password** and a specific set of permissions that controls which endpoints it can access.

<CardGroup cols={2}>
  <Card title="Production Portal" icon="arrow-up-right-from-square" href="https://jobticket-developer.ticket-plus.app/dashboard/api-keys">
    Manage production API keys
  </Card>

  <Card title="Staging Portal" icon="arrow-up-right-from-square" href="https://jobticket-developer-staging.ticket-plus.app/dashboard/api-keys">
    Manage staging API keys
  </Card>
</CardGroup>

## How to authenticate

Combine your username and password with a colon, Base64-encode the result, and pass it in the `Authorization` header on every request.

```
Authorization: Basic Base64(username:password)
```

### Example

```bash theme={null}
curl https://v1-api.ticket-plus.app/employees \
  -u "your_username:your_password"
```

The `-u` flag in `curl` handles the Base64 encoding automatically. In other HTTP clients, encode `username:password` with Base64 yourself and set the header manually:

```
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
```

## Permissions

Each API key is granted one or more permissions in the Developer Portal. The table below lists every permission and the endpoints it unlocks.

| Permission             | Description                                                                                                                                                                     | Endpoints                                                                                                                                                                                                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `view-employees`       | Read employee records and their documents.                                                                                                                                      | [List Employees](/v1/endpoint/employees-list), [Get Employee](/v1/endpoint/employees-get), [List Employee Documents](/v1/endpoint/employees-documents), [List All Documents](/v1/endpoint/documents-list), [Get Document](/v1/endpoint/documents-get), [Download Document](/v1/endpoint/documents-download) |
| `view-hr-integrations` | Read HR integration records and sync status.                                                                                                                                    | [List HR Integrations](/v1/endpoint/hr-integrations-list), [Get HR Integration](/v1/endpoint/hr-integrations-get)                                                                                                                                                                                           |
| `view-billing`         | Read billing items — the charges on your company's invoices, including per-employee ticket charges, pricing, and billing periods. Use the ticket charges to build payroll data. | [List Billing Items](/v1/endpoint/billing-items-list), [Get Billing Item](/v1/endpoint/billing-items-get), [Export Billing Items](/v1/endpoint/billing-items-export)                                                                                                                                        |
| `add-employees`        | Create new employee records during a sync.                                                                                                                                      | [Trigger HR Sync](/v1/endpoint/hr-integrations-sync)                                                                                                                                                                                                                                                        |
| `update-employees`     | Update existing employee records during a sync.                                                                                                                                 | [Trigger HR Sync](/v1/endpoint/hr-integrations-sync)                                                                                                                                                                                                                                                        |
| `remove-employees`     | Offboard employees no longer in the roster during a sync.                                                                                                                       | [Trigger HR Sync](/v1/endpoint/hr-integrations-sync)                                                                                                                                                                                                                                                        |

<Warning>
  The [Trigger HR Sync](/v1/endpoint/hr-integrations-sync) endpoint requires all
  four permissions — `view-employees`, `add-employees`, `update-employees`, and
  `remove-employees` — to be granted on the same API key.
</Warning>

## Servers

| Environment | Base URL                                 |
| ----------- | ---------------------------------------- |
| Production  | `https://v1-api.ticket-plus.app`         |
| Staging     | `https://v1-api-staging.ticket-plus.app` |

Use the staging server with staging credentials when building and testing your integration. Staging and production credentials are separate — they are not interchangeable.