Skip to the page

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.

TokenStarts withLives
Access tokenrkc_An hour.
Refresh tokenrkr_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.

Device code sign-in
# 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.

Refresh
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

The Rykloud API has no API keys or service accounts today. Every call is a person's session, recorded as that person. Machine identities are being built; this page will say how to use them when they ship.

What works today:

  • A job a person starts: set RYKLOUD_TOKEN to an access token and the CLI uses it instead of a stored session (or RYKLOUD_TOKEN_FILE to 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.