Authentication
Every request to the Asset API is authenticated with a bearer token. Tokens are minted in the web application by an account admin, belong to the account (not to the person who created them), and are scoped server-side to exactly one account — the token itself decides what you can see, and nothing in a request can widen it.
How tokens work
Tokens are created under Settings → API tokens (/api_tokens) in the web application. The page is visible to account admins only; creating a token asks for nothing but a Token Name, and the secret is shown on the token's page in a blurred click-to-copy block.
The ownership model matters for long-lived integrations:
- Tokens are account-owned. A token belongs to the account it was created in, not to the admin who created it. Any admin of the account can create or revoke any of the account's tokens.
- Scoped to exactly one account. The scope is enforced server-side — a token reads its own account's data and nothing else, ever. There is no way to request broader access.
- Survives personnel changes. A token keeps working if the admin who created it leaves the account; it only stops if that user's record is deleted entirely.
- Usage is tracked. Every authenticated request updates the token's
last_used_at, shown as Last Used on the API tokens page — so a stale or compromised key is visible at a glance. - Revocation is immediate. Revoking a token on
/api_tokens(the confirmation reads "Are you sure you want to revoke this API token?") kills it on the very next request.
There is no OAuth flow, no IP allowlisting, and no callback registration — a single bearer token in a header is the entire mechanism.
Create one key per integration and name it after the system that will use it (for example, a key named "auditbench" for an AuditBench connection). That keeps the Last Used column meaningful and lets you revoke one integration without breaking the others.
Sending the token
Pass the token in the Authorization header on every request. The standard scheme is Bearer; the word token is also accepted in its place.
Requests with a missing or invalid token get a 401 with an empty body. Requests with a valid token that reference something outside the token's account get a 404 — never a silently widened result. The API will not tell you whether the thing exists in someone else's account; out of scope and nonexistent look identical by design.
Header
GET /api/v1/me.json
Accept: application/json
Authorization: Bearer <token>
Request
curl https://averase.com/api/v1/assets \
-H "Authorization: Bearer $TOKEN"
Error responses
| Status | Meaning | What to do |
|---|---|---|
401 | Missing or invalid token (empty body) | Alert — the key was revoked or mistyped. Mint a fresh one on /api_tokens. |
404 | The resource is unknown or belongs to another account | Treat as "does not exist for this token". Check the account_id you're sending. |
Keeping the token safe
Treat the token like a password: store it in your integration's secret store, never in source control or client-side code. If a token leaks, any account admin can revoke it immediately from /api_tokens and mint a replacement — nothing else needs to change, since the token is the whole credential.