Start device authorization

Begins the device authorization grant. Returns a user code and a verification URL that a human opens in a browser to approve the credential, plus a device code to poll with. This is how a CLI or an unattended agent obtains a credential without a password.

POST/auth/cli/device

Request body

requiredapplication/json

Any of:

object

credentialProtectionstring

default: "os_keychain"

Allowed:os_keychainplaintext_local

installationIdstring<uuid>

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

machineCredentialstring

hostobject

Show properties

hostnamestring

max length 256

osstring

max length 256

any

any

Responses

201Success.

deviceCodestringrequired

min length 1

userCodestringrequired

min length 1

verificationUristring<uri>required

verificationUriCompletestring<uri>required

expiresInSecondsintegerrequired

max 9007199254740991

pollIntervalSecondsintegerrequired

max 9007199254740991

400The request failed validation. `field` names the offending input.

statusCodeintegerrequired

HTTP status code, repeated in the body.

min -9007199254740991 · max 9007199254740991

codestringrequired

Stable machine-readable error code, e.g. `SECRET_NOT_FOUND` or `FORBIDDEN`. Branch on this, never on the message.

messagestringrequired

Human-readable explanation. Wording may change.

fieldstring

The offending request field, present on validation failures.

404The resource does not exist, or is not visible to this credential.

statusCodeintegerrequired

HTTP status code, repeated in the body.

min -9007199254740991 · max 9007199254740991

codestringrequired

Stable machine-readable error code, e.g. `SECRET_NOT_FOUND` or `FORBIDDEN`. Branch on this, never on the message.

messagestringrequired

Human-readable explanation. Wording may change.

fieldstring

The offending request field, present on validation failures.

429Rate limited. Retry after the interval named in the response.

statusCodeintegerrequired

HTTP status code, repeated in the body.

min -9007199254740991 · max 9007199254740991

codestringrequired

Stable machine-readable error code, e.g. `SECRET_NOT_FOUND` or `FORBIDDEN`. Branch on this, never on the message.

messagestringrequired

Human-readable explanation. Wording may change.

fieldstring

The offending request field, present on validation failures.

500Unexpected server error. The body never carries internal detail.

statusCodeintegerrequired

HTTP status code, repeated in the body.

min -9007199254740991 · max 9007199254740991

codestringrequired

Stable machine-readable error code, e.g. `SECRET_NOT_FOUND` or `FORBIDDEN`. Branch on this, never on the message.

messagestringrequired

Human-readable explanation. Wording may change.

fieldstring

The offending request field, present on validation failures.

Request

curl -X POST "https://api.varsafe.dev/auth/cli/device" \
  -H "Content-Type: application/json" \
  -d '{
  "credentialProtection": "os_keychain",
  "installationId": "<uuid>",
  "machineCredential": "grant",
  "host": {
    "hostname": "string",
    "os": "string"
  }
}'

const response = await fetch("https://api.varsafe.dev/auth/cli/device", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "credentialProtection": "os_keychain",
  "installationId": "<uuid>",
  "machineCredential": "grant",
  "host": {
    "hostname": "string",
    "os": "string"
  }
})
});

import requests

response = requests.post(
    "https://api.varsafe.dev/auth/cli/device",
    headers={
        "Content-Type": "application/json"
    },
    json={
  "credentialProtection": "os_keychain",
  "installationId": "<uuid>",
  "machineCredential": "grant",
  "host": {
    "hostname": "string",
    "os": "string"
  }
},
)

Response

{
  "deviceCode": "string",
  "userCode": "string",
  "verificationUri": "<uri>",
  "verificationUriComplete": "<uri>",
  "expiresInSeconds": 0,
  "pollIntervalSeconds": 0
}