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 availability

API access is available on all plans, including Free.

Internal gate	Animo plan	Grants
`USE_API`	All plans	Company-scoped REST endpoints
`USE_INTEGRATIONS`	Pro	Webhook attach/update/detach

Scope requirements per route group

Routes enforce scopes via middleware. A token must include the scope listed on each endpoint. Webhook endpoints also require the Integrations feature (USE_INTEGRATIONS gate, Pro plan).

Error responses

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

Start here

Reference

Endpoints

Authentication

Authentication

Sending the token

Obtaining a token

Personal access token (recommended for integrations)

OAuth2 authorization code flow

Token refresh

Default scopes

All scopes

Plan availability

Scope requirements per route group

Error responses

​Authentication

​Sending the token

​Obtaining a token

​Personal access token (recommended for integrations)

​OAuth2 authorization code flow

​Token refresh

​Default scopes

​All scopes

​Plan availability

​Scope requirements per route group

​Error responses

​Related

Authentication

Sending the token

Obtaining a token

Personal access token (recommended for integrations)

OAuth2 authorization code flow

Token refresh

Default scopes

All scopes

Plan availability

Scope requirements per route group

Error responses

Related