Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
PricingDashboard
GuidesAPI ReferenceCLI
API ReferenceAccount and accessAccount

Poll a device login for its session

Polls a device login: pending until the user approves, then returns the CLI session credential exactly once; denied or expired codes say so. RFC 8628-style polling: while the code is pending, answers 400 authorization_pending; faster than the returned interval, 429 slow_down; denied, 403 access_denied; expired or unknown, 410 expired_token. On the first poll after approval, mints and returns the one-time CLI session credential; every poll after that (the code was already collected) also answers expired_token, so the token is delivered to exactly one caller.

Required permission

Requires no authentication.

POST
/v1/cli-auth/token

Request Body

application/json
  1. body
deviceCode*string

Response Body

Approved; here is the session

application/json
  1. response
token*string

Bearer credential, prefix ocs_; shown once.

tokenType*string

Always Bearer.

expiresAt*string
Formatdate-time
orgId*string
orgName?string
userId*string
email*string
sessionId*string

This session's id: what orl auth logout revokes with DELETE /v1/me/cli-sessions/{id}.

Example Request
curl -X POST 'https://api.openrelay.inc/v1/cli-auth/token' \  -H 'Content-Type: application/json' \  -d '{  "deviceCode": "string"}'
Example Response
{  "token": "string",  "tokenType": "string",  "expiresAt": "2019-08-24T14:15:22Z",  "orgId": "string",  "orgName": "string",  "userId": "string",  "email": "string",  "sessionId": "string"}

Start a CLI device login (no auth) POST

Starts the orl auth login device flow: returns a device code for the CLI to poll and a 6-digit user code for a signed-in person to confirm. No API key or session is required: this is how an unauthenticated CLI starts the flow that gets it one. The code expires in 10 minutes. deviceName is the requesting host's best-effort hostname, shown on the approval page so the signed-in user can recognize their own terminal before confirming the code.

Look up a pending device login GET

Shows the approval page what a pending device login is: the requesting device's name, the IP that started the flow and when. User sessions only. Approving or denying a CLI login is something only a signed-in person does, so an API key can never call this. Rate limited per user and per IP, the brute-force mitigation for a guessed 6-digit code.