# Authentication

Source: https://docs.astalty.com.au/developers/api/authentication

> How to authenticate API requests with your Astalty API key, plus rate limits and error responses.

Astalty Premium - This feature is part of the Astalty Premium plan. See What Premium includes.

## Overview

The Astalty API authenticates each protected request with an **API key** used as a Bearer token. Follow [Create and Manage an API Key](https://docs.astalty.com.au/developers/api/how-to-set-up-an-api-key) before making your first request.

> **Treat your API key like a password**
>
> A **Full Access** key can read and change almost all account data exposed by the API. Most actions are not limited by the key owner's other role permissions. Finance access is the exception and still depends on the key owner's Finance permission. Store keys in a secrets manager, keep them out of source control and replace a key if it may have been exposed.

## Authenticating a request

Send the key in the `Authorization` header as a **Bearer** token. Send `Accept: application/json` so error responses are returned as JSON.

```bash
curl https://api.app.astalty.com.au/public/v1/participants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

A request with a missing, malformed or revoked key is rejected with a `401 Unauthorized` response. A key also stops working while its owner is deactivated. If an integration unexpectedly returns `401`, check the key and its owner's account status before replacing credentials.

## Access levels and permissions

Every API key has an **access level**. You choose it when creating the key and can change it later.

| Access level    | What the key can do                                                        |
| --------------- | -------------------------------------------------------------------------- |
| **Full Access** | Read, create, update and delete data.                                      |
| **Read Only**   | Read data only. Create, update and delete requests return `403 Forbidden`. |

For permissions other than Finance, an API key receives account-level access to the operations allowed by its access level. It can therefore reach data that the key owner may not be able to reach in the Astalty interface. Finance endpoints remain limited by the key owner's Finance module permission.

The Account Owner controls which Admins can create and manage keys. See [Grant API Key and Webhook Access](https://docs.astalty.com.au/guide/roles-and-permissions#granting-api-key-and-webhook-access).

See [How to set up an API key](https://docs.astalty.com.au/developers/api/how-to-set-up-an-api-key#access-levels) for details on choosing and changing access levels.

## Rate limiting

The public API's default limit is **60 requests per minute per API key owner**. Your account may have a different limit configured by Astalty. Keys belonging to the same user share that user's limit. Requests over the limit return `429 Too Many Requests`. Honour the response headers, wait before retrying and avoid large bursts.

## Error responses

The API uses standard HTTP status codes and returns a JSON body describing the problem.

| Status                     | Meaning                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------- |
| `200` / `201` / `204`      | Success. A `204` response has no body                                                                |
| `401 Unauthorized`         | Missing, invalid or revoked API key                                                                  |
| `403 Forbidden`            | The key doesn't have permission for this action (including write requests made with a Read Only key) |
| `404 Not Found`            | The resource doesn't exist (or isn't visible to your account)                                        |
| `422 Unprocessable Entity` | Validation failed. Check the `errors` object for field messages                                      |
| `429 Too Many Requests`    | Rate limit exceeded                                                                                  |

A typical error body looks like this:

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."]
  }
}
```

## Request history

The API Dashboard records requests made with your account's keys. Select a request to inspect its status, time, source user, IP address, request body and response body. See [Review API Request History](https://docs.astalty.com.au/developers/api/how-to-set-up-an-api-key#api-dashboard).