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

# Authentication

# Authentication

The Animo API uses **Laravel Passport** (OAuth2) with bearer tokens. Every request to `/api/v1/*` must include a valid access token.

## Sending the token

Include the token in the `Authorization` header:

```http theme={null}
GET /api/v1/user HTTP/1.1
Host: {your-domain}
Authorization: Bearer {access_token}
Accept: application/json
```

## Obtaining a token

### Personal access token (recommended for integrations)

1. Sign in to Animo as the user whose data the integration will access.
2. Open the admin panel and navigate to user API token settings.
3. Create a new personal access token and select the required scopes.
4. Copy the token immediately — it is shown only once.

Personal access tokens expire after **one year** (`Passport::personalAccessTokensExpireIn`).

### OAuth2 authorization code flow

For third-party apps that act on behalf of users:

1. Register an OAuth client in Passport.
2. Redirect the user to authorize:
   ```http theme={null}
   GET /api/oauth/authorize
   ```
3. Exchange the authorization code for an access token:
   ```http theme={null}
   POST /api/oauth/token
   Content-Type: application/json

   {
     "grant_type": "authorization_code",
     "client_id": "{client_id}",
     "client_secret": "{client_secret}",
     "redirect_uri": "{redirect_uri}",
     "code": "{authorization_code}"
   }
   ```

OAuth routes are mounted at `/api/oauth`.

### Token refresh

Authenticated users can refresh tokens via:

```http theme={null}
POST /api/oauth/token/refresh
```

(Requires an active web session.)

## Default scopes

When creating a token without explicitly selecting scopes, these are granted by default:

| Scope            | Description                         |
| ---------------- | ----------------------------------- |
| `user:read`      | Retrieve the user info              |
| `companies:read` | Get the companies available to user |

## All scopes

| Scope                   | Description                                                                         |
| ----------------------- | ----------------------------------------------------------------------------------- |
| `user:read`             | Retrieve the user info                                                              |
| `companies:read`        | Get the companies available to user                                                 |
| `activations:read`      | Access activations and the submissions and leads through them                       |
| `activations:subscribe` | Subscribe to activation events (new submissions)                                    |
| `events:read`           | Access events from the companies of the user                                        |
| `events:create`         | Create new events for the companies of the user                                     |
| `events:update`         | Update events belonging to the companies of the user                                |
| `events:delete`         | Delete events belonging to the companies of the user                                |
| `forms:read`            | Access forms from the companies of the user                                         |
| `forms:create`          | Create form on any of the user's companies                                          |
| `forms:update`          | Modify forms on any of the user's companies                                         |
| `forms:delete`          | Delete any of the forms available on the the user's companies                       |
| `leads:read`            | Access leads from the companies of the user                                         |
| `leads:subscribe`       | Subscribe to lead events (creation, update, deletion)                               |
| `meetings:read`         | Access booked meetings and the submissions and leads through them                   |
| `meetings:subscribe`    | Subscribe to meeting events (new bookings, cancellations, no-show, ratings...)      |
| `orders:read`           | Access the list of orders for any of the events organized by the user's companies   |
| `orders:cancel`         | Allow to cancel free orders for any of the events organized by the user's companies |
| `orders:curate`         | Approve or deny any pending orders from the users events                            |
| `orders:create`         | Register tickets on the name of your attendees from the API.                        |
| `submissions:read`      | Access submissions from leads belonging to companies of the user                    |
| `submissions:subscribe` | Subscribe to submission events (new submissions)                                    |
| `ticket-types:read`     | Access ticket types from the events of the user                                     |
| `ticket-types:create`   | Create ticket types on any of the user's events                                     |
| `ticket-types:update`   | Modify ticket types on any of the user's events                                     |
| `ticket-types:delete`   | Delete ticket types available on the the user's events                              |

> **Note:** Scopes `leads:read`, `submissions:read`, and `meetings:read` are registered but have no matching `GET` endpoints yet.

## Plan requirement

API access requires an active **Pro** plan on each company you integrate with. Manage billing at **[https://app.animo.co/admin/settings/billing](https://app.animo.co/admin/settings/billing)**.

| Internal gate      | Animo plan | Grants                            |
| ------------------ | ---------- | --------------------------------- |
| `USE_API`          | **Pro**    | All company-scoped REST endpoints |
| `USE_INTEGRATIONS` | **Pro**    | Webhook attach/update/detach      |

Without Pro:

* `GET /api/v1/companies` returns `200` with an **empty** `data` array (easy to misread as "no companies")
* Direct calls to `/api/v1/{company}/…` return `403`

## Scope requirements per route group

Routes enforce scopes via middleware. A token must include the scope listed on each endpoint. Company-scoped routes additionally require the Pro plan (`USE_API` gate). Webhook endpoints also require the Integrations feature (`USE_INTEGRATIONS` gate).

## Error responses

| Status             | Meaning                                                                     |
| ------------------ | --------------------------------------------------------------------------- |
| `401 Unauthorized` | Missing, expired, or invalid token                                          |
| `403 Forbidden`    | Valid token but missing required scope, subscription gate, or policy denial |

## Related

* [Conventions](conventions.md)
* [API index](index.md)