Using the API
Authentication
Every call is made by a person, through a session of their Rykon account, with exactly the rights that person has in the console.
Send a bearer token
Every operation except the two that make a token takes an access token in the Authorization header. Access tokens start with rkc_. The examples in these docs read it from $RYKLOUD_TOKEN, the same variable the CLI reads.
curl https://api.rykloud.com/v1/me/organisations \
-H "Authorization: Bearer $RYKLOUD_TOKEN"No token answers 401 unauthorized; an ended, signed out or revoked session answers 401 session_ended. Only the operations in the API reference accept a session: any other route answers 404.
Sessions
A session starts when a person signs in at the Rykon account (id.rykloud.com) for the client rykloud-cli and the resulting ID token is exchanged once at POST /v1/cli/sessions. rykloud auth login does all of it, in the browser or with a code (--device). The account's email address must be confirmed.
| Token | Starts with | Lives |
|---|---|---|
| Access token | rkc_ | An hour. |
| Refresh token | rkr_ | Spent on every use for a new pair; 30 days unused at most, and the session itself ends after 90 days. |
Rykloud keeps only a hash of each token. A refresh token used twice means someone else holds a copy, so the whole session ends for both. People see and end their sessions with rykloud auth sessions and rykloud auth revoke (CLI sessions), and in the console.
Read and write scope
A session is read or write (the default). A read session can call every operation marked read and sees everything the person may see; any write answers 403 scope_insufficient with "detail": { "needs": "write" }. Each operation's page says which it needs. Make a read session for anything that only looks: rykloud auth login --scope read --name reports.
Scope only narrows. Within it, the person's roles decide everything else, as in the console: an owner's approval, a maintainer's change, an organisation they are not in (404).
Signing in without the CLI
The CLI's sign-in is standard OAuth 2.0 against the Rykon account, so your own tool can do the same: the device code flow (RFC 8628) for the public client rykloud-cli with the scopes openid email profile, then the exchange. Poll at the interval the first answer gives and slow down by five seconds when told slow_down; codes last ten minutes.
# 1. Ask the Rykon account for a code (client rykloud-cli)
curl -s https://id.rykloud.com/application/o/device/ \
-d client_id=rykloud-cli -d scope="openid email profile"
# answers device_code, user_code, verification_uri, interval
# 2. Open verification_uri, sign in and enter user_code. Meanwhile poll,
# every interval seconds, until it answers an id_token:
curl -s https://id.rykloud.com/application/o/token/ \
-d grant_type=urn:ietf:params:oauth:grant-type:device_code \
-d device_code="$DEVICE_CODE" -d client_id=rykloud-cli
# 3. Exchange the ID token (at most 10 minutes old) for a session
curl -s -X POST https://api.rykloud.com/v1/cli/sessions \
-H "Content-Type: application/json" \
-d '{"idToken": "'"$ID_TOKEN"'", "scope": "read", "device": "billing report"}'The answer holds accessToken, refreshToken and their expiry times. When the access token expires, spend the refresh token for a new pair, and keep the new refresh token: the old one no longer works.
curl -s -X POST https://api.rykloud.com/v1/cli/sessions/refresh \
-H "Content-Type: application/json" \
-d '{"refreshToken": "'"$RYKLOUD_REFRESH_TOKEN"'"}'Programs, CI and scripts
No machine credential yet
What works today:
- A job a person starts: set
RYKLOUD_TOKENto an access token and the CLI uses it instead of a stored session (orRYKLOUD_TOKEN_FILEto a file holding it, read on every request). An access token lives an hour. - A longer-running tool can hold a session's refresh token and refresh as above. That token is the person's credential: give the session read scope unless it must write, name it for the tool (
device), keep it in a secret store, and revoke it when the tool is retired.
Rykon Mail already has its own API keys and service accounts for machines; see Rykon Mail and Rykon AI.
Keep tokens secret
- Never put a token in a URL, a commit or a log line. The CLI keeps sessions in the system keychain, or a file only you can read where there is none.
- Operations that answer a secret (a database's connection details, a secret's value) are marked on their pages, answered with
cache-control: no-store, and recorded in activity. - Lost a laptop? End its session from another machine with
rykloud auth revoke, or in the console.