Skip to main content

​
Bearer token

Send your token in the Authorization header on every request:
Both personal tokens and account tokens are accepted. The token resolves to an account, and requests are limited to the environments that token may view.

​
Creating a token

Generate a token in the Elementary app, then send it as the bearer token shown above. The token is displayed only once — copy it and store it securely.

Personal token

User → Personal Tokens. User-scoped: inherits your own workspace permissions, so it can read exactly the environments and assets you can. Best for personal scripts and exploration.

Account token

Account → Account Tokens. Account-scoped with “Can View” permissions and not tied to a single user. Best for shared services, CI, and integrations. Creating one requires the Manage account tokens permission.
In either case, click Generate token and copy the value into the Authorization: Bearer header.

​
Which token should I use?

Both work identically on the wire — the difference is what the token is tied to:
  • Use a personal token for interactive work: notebooks, one-off scripts, and local exploration. Its access mirrors yours and is revoked automatically when your own access changes, so it’s convenient but tied to your account lifecycle (a token stops working if you leave the workspace or lose a permission).
  • Use an account token for anything long-lived or shared: CI jobs, backend services, and third-party integrations. It isn’t attached to a person, so it keeps working through team changes and offboarding — which also makes it the token you must rotate and guard most carefully.
Treat tokens like passwords: never share or commit them, rotate them regularly, and revoke a token immediately if it may have been exposed.

​
Environment scope

Every resource except GET /environments is nested under an environment:
Call GET /environments first to discover the ids you can access. Passing an env_id you don’t have access to returns 403.

​
Visibility & permissions

Access is governed by your token’s role at three levels:
  1. Environment access — the token must be able to view the environment (as returned by GET /environments). Otherwise every request under that env_id returns 403.
  2. Resource scope — the asset, column, and lineage endpoints require the assets view scope. A role that can reach the environment but isn’t granted the assets resource returns 403.
  3. Per-asset access — see below.
If your token’s role is restricted to a subset of an environment’s assets (resource-group permissions), the API only ever returns the assets — and the columns and lineage edges derived from them — that you’re allowed to see:
  • List endpoints silently omit assets you can’t view. Asset-lineage edges are returned only when both of their endpoints are visible to you; an edge that touches a restricted asset is dropped entirely.
  • Column-lineage edges are returned only when the downstream column’s asset is visible to you. A returned edge’s upstream_column_id may reference a restricted upstream asset; only the id is exposed, not its metadata.
  • Get-one endpoints (/assets/{id}, /columns/{id}) return 404 for an object you can’t view — the same response as a nonexistent object, so the API never discloses that a restricted asset exists.
Because filtering is applied per page after rows are read, a page may contain fewer than limit items while has_more is still true. Always iterate on has_more, not on item count — see Pagination.

​
Errors

See Errors for the full error contract.