Authentication and permissions

Send a bearer token#

Every customer API request requires these headers:

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

Use Content-Type: application/json for JSON request bodies. Tokens are created in Settings → API Access by an active account administrator. Select a 30-day, 90-day, or one-year lifetime. Tokens are shown once; store them securely and use one named token per integration.

Organization scope#

A token stays tied to the organization where it was created, even when its creator switches organizations in the app. Do not send tenant_id or account_id to choose an organization; list and timeline requests prohibit these fields. Use a separate token for each organization.

The organization API reference covers settings, logos, exports, and deletion using customer API tokens. These actions use /api/v1 and the organization permissions below. Organization creation and switching are unavailable to customer tokens, including Full Access and older tokens. Create organizations in the app and issue a separate token for each organization.

Access stops when the token expires or is revoked, or when its creator is deactivated, removed from the organization, or no longer an account administrator. Manage and revoke tokens in API Access. Create and deploy a replacement token before revoking the old one during rotation.

Permission presets#

Read Only includes organizations:read, users:read, asset-categories:read, subscription-categories:read, asset-events:read, person-events:read, location-events:read, and the four inventory Read permissions. Full Access includes all 72 explicit permissions, including five organization permissions, four user permissions, four asset category permissions, four subscription category permissions, four permissions each for asset, person, and location event setup, eight timeline editing permissions, assets:tracking, reports:read, and billing:read. The Read Only preset does not include billing, timeline editing, GPS, or reports. Custom lets you select each permission. Existing tokens keep the permissions they were issued with, but the former organization creation permission no longer grants access. Create a replacement token when an integration needs newly available access.

Organization permissions#

Organization actions do not grant access to other organizations or permission to change the token's scope.

User permissions#

See Users and invitations. These permissions do not allow global profile or authentication changes. The token creator cannot be changed or removed through these endpoints. Grant users:permissions only when the integration should be able to give members full administrator access.

Billing permissions#

Select this permission in Custom or issue a new Full Access token. Existing tokens retain their permissions. Billing access does not allow portal sessions, payment-method changes, or subscription management. See Plan and usage and Billing invoices.

Asset category permissions#

These permissions are independent of asset record permissions. See Asset categories and custom fields. Every category and field write requires an Idempotency-Key.

Subscription category permissions#

These permissions are independent of subscription record permissions. See Subscription categories and custom fields. Every category and field write requires an Idempotency-Key.

Record permissions#

Replace resource with assets, people, locations, or subscriptions.

These permissions are independent. Write access does not imply Read. Creation options require Create, even though the request uses GET.

Lookup permissions#

The paginated lookup endpoints use existing Read permissions and return IDs and names. They support integrations that need searchable choices without fetching full records.

Asset timeline options for asset_event with kind=people need assets:read and people:read. Timeline options for todo with kind=users need the record's :read and :todos permissions plus users:read. Reading these choices does not require :timeline:update.

Workflow permissions#

Workflow GET requests require the workflow’s permission. Read Only tokens cannot list workflow to-dos or assignment choices. The organization-wide to-do endpoints need at least one :todos permission and only return to-dos on record types the token holds :todos for. Subscription billing and its options require subscriptions:update.

Actions with multiple permissions#

Asset subscription assignments require assets:assignments and subscriptions:update. Subscription assignment endpoints require subscriptions:assignments and the target resource’s :update permission. People/location assignment endpoints likewise need the source resource’s :assignments and the target’s :update. These extra requirements also apply to their GET lists and options.

Asset decommissioning requires assets:lifecycle and assets:delete, including its options lookup. Logging a person or location event whose type changes status requires the resource’s :events and :lifecycle permissions. Subscription cancellation and retirement require subscriptions:lifecycle and subscriptions:delete. Deleting a location space requires locations:lifecycle and locations:delete.

Read related history#

The parent record’s Read permission allows its timeline. Related asset events also require assets:read; related subscription events require subscriptions:read. References only reveal resources your token can read. A person’s timeline can therefore contain fewer events with a narrowly scoped token. Use the timeline endpoint pages for details.

Timeline editing permissions#

Replace resource with assets, people, locations, or subscriptions.

Reading a single entry needs only resource:read. Entries of type todo also need resource:todos. See get a timeline entry.

Comment writes use the token creator as the author. Editing or deleting requires that administrator to be the comment's author, even with Full Access. You can reply to another author's top-level comment. These rules apply to both single comment operations and bulk changes through PATCH. To-do comment writes additionally require the record's :todos permission.

GPS and report permissions#

assets:read alone never reveals GPS positions. New Full Access tokens include both permissions; Read Only and existing tokens do not.

Asset event permissions#

These permissions configure asset event setup independently of asset-record permissions. All writes require Idempotency-Key. Existing keys keep their current permissions.

Person and location event permissions#

Replace type with person or location.

These configure person event setup and location event setup, independently of each other, of asset event setup, and of record permissions. Logging an event against a person or location uses people:events or locations:events instead.