# Authentication

Every request carries the API key in the `Authorization` header:

```http
GET /v1/clients HTTP/1.1
Host: api.invoicing.proradius.co
Authorization: Bearer <your API key>
Accept: application/json
```

Send the key exactly as it was shown when you created it. Always call the API over HTTPS and keep the key on your
server. Never put it in a mobile app or a web page.

## The organization header

An API key belongs to one organization. The API reads the organization from the key, so you do **not** send an
`Organization-Id` header. If you send one, it is ignored and replaced by the key's organization.

The `Organization-Id` header is only used by the PROradius apps themselves, which sign in as a user and can switch
between organizations.

## Abilities

Each key holds a list of abilities, in the form `module:action`. An endpoint checks the ability it needs and answers
`403` when the key does not have it. The [API reference](/api/) names the ability on every operation.

| Ability | Allows |
| --- | --- |
| `clients:read` | List and read clients. Also lets the key subscribe to `client.*` webhooks. |
| `clients:create` | Create clients. |
| `clients:update` | Update clients. |
| `clients:delete` | Delete clients. |
| `tickets:read` | List and read service jobs, boards, job types and technicians. Also lets the key subscribe to `ticket.*` webhooks. |
| `tickets:create` | Create service jobs. |
| `tickets:update` | Update, move, archive, comment on, start and cancel jobs. Create and update job types. |
| `tickets:delete` | Delete service jobs. |
| `tickets:schedule` | Schedule and unschedule a visit, or create a job with a technician. |
| `tickets:complete` | Complete a job and read its completion preview. |
| `tickets:dispatch` | Book a technician over a conflict (`override` with a reason) when scheduling. |
| `invoices:create` | Needed together with `tickets:complete` when a completion creates an invoice, and for `create-invoice`. |
| `invoices:read` | Subscribe to `invoice.*` webhooks. |
| `client_payments:read` | Subscribe to `payment.*` webhooks. |
| `webhooks:read` | List webhook endpoints, topics and deliveries. |
| `webhooks:manage` | Everything in `webhooks:read`, plus create, update, delete, roll the secret, test and resend. |

A key created with no abilities holds `*`, which allows everything. Choose explicit abilities for every
production key.

### Ticket boards

A key can also be limited to some ticket boards. It then sees and changes only jobs on those boards. Jobs on other
boards answer `404`, as if they did not exist.

## Failed authentication

A missing, unknown or revoked key answers `401`:

```json
{ "status": false, "error": { "message": "Unauthenticated." } }
```

A valid key without the needed ability answers `403`:

```json
{ "status": false, "error": { "message": "This action is unauthorized." } }
```

See [API key settings](/concepts/api-keys/) for the disabled key, IP allow-list and daily limit responses.