On this page
Keys and scopes
Secret and publishable keys, organization-wide or environment-scoped, with per-service permissions.
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.
Never ship a secret key
Never put a secret key in client-side code. A browser or a mobile app gets a publishable key, which cannot read or write your resources even if someone reads it out of the bundle.
What a key carries
| Field | Type | What it is |
|---|---|---|
kind | string | Whether the key is a secret key or a publishable key. |
mode | string | live or test, fixed in the key string when the key is made. A key may act only on an environment in the same mode. |
scopes | string[] | What the key may do, each scope naming a service and an action. |
expire_time | string | The time after which the key stops working, when you set one. |
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:readAdd --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": ["access:read", "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"Letting an agent act for you
A delegation lets a service act for you without holding your key. You make it
once, signed in or with your own sylphx login key, and name the service's
principal, the agent it acts as, and the scopes it may use:
sylphx api POST /v1/access/delegations -d '{
"org": "'$ORG_ID'",
"actor": "orgs/'$ORG_ID'/projects/'$PROJECT_ID'/envs/'$ENV_ID'/agents/*",
"delegate": "'$SERVICE_PRINCIPAL'",
"scopes": ["work:read", "work:write"]
}'Delegations last at most 90 days. An API request that omits expire_time ends
90 days after creation; a longer explicit expiry is refused. In the console at
/{orgSlug}/~/delegations, a request naming no expiry instead gets a visible
one-hour delegation expiry. This is separate from the one-hour lifetime of
tokens minted from it. The review shows the exact principal id and its live key
labels read from Access, not a name supplied by the link. Denying records
delegation.deny in the organization audit log and creates no delegation or key.
Each scope must be one you hold yourself; wildcards and scopes that manage keys
or members are refused. The service's own key, which holds access:delegate,
then exchanges the delegation for a key that lasts at most an hour, using the
standard OAuth token exchange:
curl https://api.sylphx.com/v1/access/oauth/token \
-H "Authorization: Bearer $SERVICE_KEY" \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token=$DELEGATION_ID \
-d subject_token_type=urn:sylphx:params:oauth:token-type:delegation \
-d actor_token=orgs/$ORG_ID/projects/$PROJECT_ID/envs/$ENV_ID/agents/owner \
-d actor_token_type=urn:sylphx:params:oauth:token-type:agent \
-d scope=work:writeThe answer's sub is you and act.sub is the agent; /v1/whoami with the new
key shows the same as principal and actor. Deleting the delegation
(DELETE /v1/access/delegations/{delegation_id}) stops every key made from it
at once, and so does losing your role in the organization.
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.
Environment secrets
Environment secrets hold values your services read at runtime. They are separate from the Access keys that authorize API calls. Delete a management secret explains the API and permissions for deleting a secret.