Skip to main content
A scoped key is a user’s API key that carries statements narrowing what it may do. The user still needs a role that allows the action, and the scope narrows that, never augments it. Only a user’s API key takes a scope. A service account token does exactly what the service account’s roles allow, so a job that needs less gets a service account of its own with a narrower role.
Preview. Not available yet.

Scope

A scope is a list of statements, set when the key is issued. A key with no scope may do everything its user may do.
POST /v2/iam/api_keys
A request with this key needs an allow from the user’s grants and an allow from the scope. The scope never augments the grants. Had it listed connection.*, the key still could not touch connections unless a granted role allowed them. A read-only user who scopes a key to every action gets a read-only key.

Networks

A key also names the networks it accepts requests from. A request from any other address answers 401.
POST /v2/iam/api_keys
A service account token names its networks the same way, when it is issued at /v2/iam/service_accounts/{id}/tokens.

Key Rules

The organization’s guardrail can require a scope on every API key and cap how long an API key or a service account token lives, through require_scope and max_lifetime_days in /v2/iam/settings.

Keys Without a Scope

/v2/api_keys keeps working. A key issued there has no scope and does whatever its user may do.