All endpoints

DocsAPIGetting a key

POST/device-authorizations

Start a device authorization

How a terminal with no credential gets one.

Auth header

No key needed: this is how something without a key gets one.

Request body

  • clientNamestringrequired

    How this client will name itself on the approval screen, e.g. "tagsentry-cli 0.1.0 (darwin 24.0)". Displayed to a human as text and trusted for nothing.

  • projectHintstringoptional

    The directory or package name the client is running in, so a person with two terminals open can tell which one asked.

  • scopesarray of stringrequired

    The scopes the issued key should carry. Restricted to what a terminal is allowed to be granted this way (see lib/api/deviceAuthorization.ts). A request for anything outside that set is refused whole, so the approval screen can never be made to ask a human for a scope this flow cannot grant.

Example request

curl -X POST "https://app.tagsentry.ai/api/v1/device-authorizations" \  -H "Content-Type: application/json" \  -d '{"clientName":"…","projectHint":"…","scopes":["…"]}'

Response 201

  • deviceCodestringrequired

    Your secret. Send it to /device-authorizations/token. Never displayed to a human.

  • userCodestringrequired

    What the person reads off your output, e.g. "BQ7K-F3XM".

  • verificationUrlstringrequired

    Where the human approves. Show this even when you also open a browser.

  • verificationUrlCompletestringrequired

    The same page with the code already filled in. This is the one to open.

  • verification_uri_completestringrequired

    RFC 8628's name for verificationUrlComplete: the same link, for a generic device-flow client.

  • relayToHumanstringrequired

    One sentence for the person: the link to open, the code to compare, and the deadline. An agent says it to its human VERBATIM: they cannot see your tool output, and nothing else will tell them a request is waiting. Never contains the device code.

  • expiresAtstringrequired

    ISO-8601 timestamp, UTC.

  • expiresInintegerrequired

    Seconds until this authorization dies.

  • intervalintegerrequired

    Seconds to wait between polls.

Example response

{  "deviceCode": "ABCD-EFGH",  "userCode": "ABCD-EFGH",  "verificationUrl": "https://silverpine.example/",  "verificationUrlComplete": "https://silverpine.example/",  "verification_uri_complete": "…",  "relayToHuman": "…",  "expiresAt": "2026-09-26T14:02:00.000Z",  "expiresIn": 0,  "interval": 0}
More about this endpoint

UNAUTHENTICATED, and the only operation on this surface that is.

You get a userCode to show the person and a deviceCode to keep. Send them to verificationUrlComplete, where they sign in (creating an account if they have none) and approve or refuse the request. Poll POST /device-authorizations/token with the device code until it answers.

IF YOU ARE AN AGENT, say relayToHuman to your human, verbatim, before you start polling. They cannot see your tool output, and no screen of ours will prompt them: a request belongs to nobody until it is approved, so we never show it to anyone who did not open its link.

WHY THERE IS NO ENDPOINT THAT JUST CREATES AN ACCOUNT: minting an identity with nobody present means no verified email and no ceiling on abuse. A human in a browser is the control, and this grant is how a headless process borrows one.

THE KNOWN WEAKNESS, stated plainly because every implementation of this grant has it: an attacker can start a flow and talk somebody into approving it, and what they get is that person's own account. Do not send a user code to anyone. Our approval screen names the client and the directory that asked and tells a person who did not just run a CLI to press Deny.

Errors400 · 429 · 500
  • 400The request did not validate against this operation's schema.
  • 429A rate limit or quota was exceeded. The body names WHICH one.
  • 500Something failed on our side. The requestId in the body is what to quote.

Every error has the same body: { error: { code, message, requestId } }.

From the OpenAPI document, version 2026-08-26. Raw OpenAPI