API keys and scopes

A key carries scopes written as app:resource:action, can never change how the account is reached, and trades for a short-lived access token over HTTP.

Use a key with HTTP

The CLI makes this trade for you. Without it, trade your key for a token with one call. Send the key in the Authorization header:

Terminal
curl -sX POST https://auth.api.ghaym.me/v1/auth/token -H "Authorization: Bearer $GHAYM_TOKEN"

The answer is an access token:

json
{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "cloud:projects:read cloud:projects:deploy"
}

Save the access_token value, here as ACCESS_TOKEN, and send it with each call:

Terminal
curl -s https://cloud.api.ghaym.me/v1/projects -H "Authorization: Bearer $ACCESS_TOKEN"
Note

Keep the two apart. GHAYM_TOKEN holds the long-lived ghk_ key, and you only send it to the exchange. The access token is what you send to every other call.

  • Send the key only in the Authorization header. Never put it in a URL or a request body, where it could end up in logs.
  • The access token is short-lived, and it can't be refreshed. To get a new one, trade the key again.
  • You can trade a key 30 times a minute. Keep the token until it expires, instead of trading before every call.
  • The token can do what the key's scopes allow, but only what the owner can still do today.

Errors come back in RFC 9457 format. Show detail to the person rather than retrying blindly. Every type is listed under API errors.

Scopes

A scope has three parts: app:resource:action. Any part can be *, which means "all".

scope   := segment ":" segment ":" segment | meta
segment := "*" | [a-z0-9-]+
meta    := "read-only"

Examples:

  • cloud:projects:deploy: deploy projects, and nothing else.
  • cloud:projects:*: everything on projects.
  • cloud:*:read: read anything in Cloud.
  • *:*:*: everything the owner can do.
  • read-only: every read or list permission the owner has.

A key can never do more than its owner. Ghaym checks the scopes against the owner's current permissions every time the key is used. If the owner loses a permission, their keys lose it too, right away. A scope for something the owner can't do simply grants nothing.

Tip

Give each key the smallest scope that does the job. A CI deploy key doesn't need *:*:*. A dashboard needs only read-only.

What a key can never do

Some actions change how someone gets into the account. Only the person can do them, after confirming it's really them:

  • Setting or removing a password.
  • Changing the account's email.
  • Deleting the account.
  • Creating, rotating or revoking API keys.

No key can do these, and no setting changes that. So a leaked key can only do what its scopes allow. It can't take over the account, create more keys, or protect itself from being revoked.