Tokens

Workspace tokens and scoped tokens limited to projects, actions, and a lifetime, and which to use where.

Every API request carries a token. A token belongs to one workspace and acts as the user who created it. There are two kinds:

Kind	Created with	Can do
Workspace token	Settings → Access Tokens in the dashboard, or `easel login`	Everything the API offers, on every project in the workspace
Scoped token	`POST /v1/tokens`, from another token	Only the projects, actions, and lifetime you give it

Keep your workspace token on your backend, and mint scoped tokens for everything else.

Never put a workspace token in a sandbox

Generated code runs in your sandboxes, and anything it can read, it can leak. A workspace token in a sandbox can deploy to, read the variables of, and delete every app on your platform.

Most sandboxes don't need a token at all: an upload URL is the only credential an upload needs. When a sandbox or job really must call the API itself, mint a token for that one job.

Mint a scoped token

Mint a token limited to one app's project, the actions the job needs, and a lifetime just long enough for it:

const { token, secret } = await easel.tokens.create({
  name: `publish-${appId}`,
  projectIds: [project.id],
  permissions: { projects: ["read"], deployments: ["create", "read"] },
  expiresIn: 900, // seconds
});

secret is the token itself (easel_…). It's returned only in this response, so pass it straight to the job and don't store it. token describes it, with its id for revoking.

A scoped token never exceeds the token that mints it:

Its permissions are a subset of the minting token's.
Its projectIds are a subset of the minting token's projects. Omit projectIds to keep the minting token's project scope.
It expires no later than the minting token.
A token limited to projects can't have projects:create, because a project it created would be outside its own scope.

A request that breaks one of these rules fails with 400 and the code token_scope. For the allowed lifetimes, see Limits.

Permissions

Each permission is a resource and an action, written resource:action:

Resource	Actions
`projects`	`read`, `create`, `update`, `delete`
`deployments`	`read`, `create`, `cancel`, `promote`
`env`	`read`, `write`
`domains`	`read`, `write`
`usage`	`read`
`webhooks`	`read`, `write`
`tokens`	`read`, `write`
`files`	`write`

Each endpoint's permission is in the API reference. Common jobs need:

Job	Permissions
Upload an archive with the API	`deployments:create`
Upload a large file list	`deployments:create`, `files:write`
Show an app's status and history to your users	`deployments:read`

What a scoped token can't reach

A token limited to projects:

Gets 404 for any other project, its deployments, and its domains, as if they didn't exist.
Gets 403 with token_scope for workspace-wide setup: wildcard domains and the branded target.
Sees and manages only webhooks limited to its projects.

Some actions also depend on the token user's role in the workspace, the same as in the dashboard. Promoting, rolling back, and creating or deleting webhooks need an Owner or Admin, whatever the token's permissions.

List and revoke tokens

GET /v1/tokens lists the tokens of the calling token's user, within its project scope. A token minted through the API only sees itself and the tokens it minted, never the token that minted it. DELETE /v1/tokens/:id revokes one, and a token can revoke itself. Revoking a token also revokes every token it minted and voids the upload URLs it minted that haven't been used.

Workspace tokens are also listed, and can be revoked, in Settings → Access Tokens.