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

Look up a pending device login

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.

Required permission

Requires the self.update permission. See Permissions for the roles and API key permissions that include it.

GET
/v1/cli-auth/device/{userCode}

Authorization

apiKey
headerAuthorizationBearer <token>

OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).

Path Parameters

userCode*string
Match^[0-9]{6}$

Response Body

The pending code's device details

application/json
  1. response
deviceName*string
clientIp?string
requestedAt*string
Formatdate-time
status*string

pending, approved, or denied.

Example Request
curl -X GET 'https://api.openrelay.inc/v1/cli-auth/device/string'
Example Response
{  "deviceName": "string",  "clientIp": "string",  "requestedAt": "2019-08-24T14:15:22Z",  "status": "string"}

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.

Approve a device login POST

Approves a pending device login, giving the CLI a 30-day session as you in the chosen org with your membership role. Needs a signed-in user session. The session has the same permissions your dashboard session has in that org, including session-only actions an API key can never perform.