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:

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)

Sign in to Animo as the user whose data the integration will access.
Open the admin panel and navigate to user API token settings.
Create a new personal access token and select the required scopes.
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:

Register an OAuth client in Passport.
Redirect the user to authorize:
```
GET /api/oauth/authorize
```

Exchange the authorization code for an access token:

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:

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.

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

​Authentication

​Sending the token

​Obtaining a token

​Personal access token (recommended for integrations)

​OAuth2 authorization code flow

​Token refresh

​Default scopes

​All scopes

​Plan requirement

​Scope requirements per route group

​Error responses

​Related