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

Start a CLI device login (no auth)

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.

Required permission

Requires no authentication.

POST
/v1/cli-auth/device

Request Body

application/json
  1. body
deviceName?string
Lengthlength <= 128

Response Body

A fresh device/user code pair

application/json
  1. response
deviceCode*string

Opaque; the CLI polls POST /v1/cli-auth/token with this.

userCode*string

The 6 digits the CLI prints for a human to enter.

Match^[0-9]{6}$
verificationUri*string
Formaturi
verificationUriComplete*string

verificationUri with ?code= pre-filled; the approval page still requires the user to confirm it matches their terminal.

Formaturi
expiresIn*integer

Seconds until the code expires (600).

interval*integer

Minimum seconds between polls; a faster poll gets slow_down.

Example Request
curl -X POST 'https://api.openrelay.inc/v1/cli-auth/device' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "deviceCode": "string",  "userCode": "string",  "verificationUri": "http://example.com",  "verificationUriComplete": "http://example.com",  "expiresIn": 0,  "interval": 0}

Update the caller's profile PATCH

Sets the signed-in user's full name, avatar URL or default organization and returns the profile. The default must be an org the user belongs to (403 otherwise). Requires a signed-in dashboard session token; API keys cannot call this endpoint.

Poll a device login for its session POST

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.