Skip to main content
POST
Start a sign-in from an agent or CLI (device flow)

Authorizations

Authorization
string
header
required

An API key of one app, sent as Authorization: Bearer <key>. Keys start with fk_test_ (test mode: sandbox senders and test data only) or fk_live_ (live mode). Keep live keys on your server; never ship them in an app or page.

Body

application/json

Optional details for a device sign-in.

claim_token
string

The claim_token from POST /v1/sandbox/keys, to claim that app when the person approves.

client_name
string

What is asking, shown to the person on the approval page, for example "flow CLI" or "Claude Code".

Maximum string length: 80

Response

The sign-in was started. Show the person the link and code, then poll for the key.

A device sign-in waiting for a person to approve it in a browser.

device_code
string
required

The secret you poll POST /v1/device/token with. Never show it to the person.

Example:

"fdc_..."

user_code
string
required

The code the person types on the approval page, eight letters in two groups. Always show it to the person, also when you show verification_uri_complete.

Example:

"WDJB-MJHT"

verification_uri
string<uri>
required

The page where the person signs in and enters user_code.

Example:

"https://api.flow.engineer/admin/device"

verification_uri_complete
string<uri>
required

The same page for this sign-in. Show this link (or a QR code of it) to the person together with user_code; the page asks them to type the code they see from you and checks it against the link, so a link on its own cannot approve a sign-in.

Example:

"https://api.flow.engineer/admin/device?code=WDJB-MJHT"

expires_in
integer
required

Seconds until the codes expire (15 minutes).

Required range: x >= 0
expires_at
string<date-time>
required

When the codes expire.

interval
integer
required

Seconds to wait between polls of POST /v1/device/token.

Required range: x >= 1