Keys and scopes

An API key authenticates a call. It has a kind, a mode and a list of scopes, and it is scoped to one organization, one project and one environment.

A key made for the organization as a whole is scoped to the organization alone: it has no project and no environment.

#The two kinds of key

A secret key begins sylphx_sk_live_ or sylphx_sk_test_, followed by a 20-character id, a 32-character secret and a 6-character checksum. It authenticates a call from a server, and you keep it there.

A publishable key begins sylphx_pk_live_ or sylphx_pk_test_, followed by an id. It carries no secret, and it is safe in a browser or a mobile app because it can hold only four scopes:

• auth:public: read the environment's public auth configuration.
• events:realtime:subscribe: subscribe to realtime events.
• observability:ingest: send observability data, such as errors captured in a browser.
• config:evaluate: read feature flag values for one user or device, never the rules behind them.

It cannot read or write your resources.

#What a key carries

A key also carries whether it has been revoked, and why. A reason is one of user, rotation, leaked, claimed, claim_expired, org_deleted, admin, role_changed or logout.

#Scopes

A scope names a service and an action, joined by a colon (<service>:<action>), so hosting:read reads a hosting resource and hosting:write changes one.

Every valid key holds access:whoami implicitly, whatever else it carries. You never have to grant it, and it cannot be granted: a create that asks for it is refused.

These are examples of the form, not the complete set: hosting:read, hosting:write, data:read, keys:use, secrets:write, events:write, billing:read, access:members:write, access:admin. A key may also hold the wildcards *:read and *:write, which cover every service the project has enabled.

A key can never hold a scope its creator does not hold: the scopes you ask for must be a subset of your own.

#Creating a key

#Environment-scoped keys

For a key that acts only in one environment, --parent names that environment. This key cannot create projects or change project-wide Hosting service definitions.

sylphx access api-keys create \
--parent orgs/{org}/projects/{project}/envs/production \
--spec.kind secret \
--spec.label ci \
--spec.scopes hosting:read,data:read

Add --dry-run to see what would be created without creating it. The commands you use by hand are sylphx access api-keys create, sylphx access api-keys revoke and sylphx access api-keys roll.

The secret is returned once, when the key is created or rolled. After that the key reports its id and the last four characters of the secret, and nothing more.

#Organization-wide keys

Use an organization-wide secret key for project-wide Hosting management, including creating a project, adding a service and changing its machine size. It has no project or environment binding. sylphx login issues this kind of key with the signing-in member's role scopes; an owner, admin or developer can follow the Hosting quickstart with that login.

For a machine, an owner or admin, or an existing organization-wide key with access:keys:write, creates a key through the management API. Set ORG_ID to the Access organization id, and run this with the creator's login or key:

sylphx api POST /v1/orgs/$ORG_ID/api_keys -d '{
  "spec": {
    "kind": "secret",
    "label": "hosting-ci",
    "scopes": ["hosting:read", "hosting:write", "hosting:deploy"]
  }
}'

The response returns status.secret once. Set SYLPHX_API_KEY to that value for the machine's calls. The requested scopes must be a subset of the creator's scopes. This organization parent is served by the management API today; the generated access api-keys create command above describes environment-scoped keys.

#Rolling a key

Rolling mints a new secret with the same scopes, and the old key keeps working until the grace period ends.

sylphx access api-keys roll \
orgs/{org}/projects/{project}/envs/{env}/api_keys/{api_key}

The grace period is 24 hours by default, and you can set it with --grace-period; anything longer than 7 days is refused. A key that a secret scanner reports as leaked is not rolled at all: it is revoked at once, so the old secret stops working immediately.

#Sending a key

Send a key as the Authorization header: the word Bearer, a space, then the key.

curl https://api.sylphx.com/v1/whoami \
-H "Authorization: Bearer $SYLPHX_API_KEY"

#A new key takes a moment

A brand-new key can take a moment to work. A call made in that moment fails with NOT_YET_PROPAGATED, which is retryable: send the call again. Errors covers that code and the rest.