Error

A valid request URL is required to generate request examples

{
  "userCode": "<string>",
  "verificationUri": "<string>",
  "verificationUriComplete": "<string>",
  "pollToken": "<string>",
  "intervalMs": 1001,
  "expiresAt": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "backend_resolution_failed",
    "message": "<string>",
    "retryable": true
  }
}

{
  "error": {
    "code": "payload_too_large",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "backend_resolution_failed",
    "message": "<string>",
    "retryable": true
  }
}

API keys

Start a CLI sign-in

What phonebase login calls first. Takes no credential. Returns a short code to show the person, the console page to approve it on, and a poll token. A signed-in person opens the page (any device will do), checks the code and approves; the CLI then collects an ordinary API key with POST /v1/cli-sessions/token.

The code works for 10 minutes and once. Starting a sign-in grants nothing on its own. This address is limited to a few sign-ins a minute.

Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404.

POST

/

v1

/

cli-sessions

Error

A valid request URL is required to generate request examples

{
  "userCode": "<string>",
  "verificationUri": "<string>",
  "verificationUriComplete": "<string>",
  "pollToken": "<string>",
  "intervalMs": 1001,
  "expiresAt": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "backend_resolution_failed",
    "message": "<string>",
    "retryable": true
  }
}

{
  "error": {
    "code": "payload_too_large",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "backend_resolution_failed",
    "message": "<string>",
    "retryable": true
  }
}

Body

application/json

Optional. What to call this computer on the approval page and on the key.

clientName

string

Usually the computer's name. Shown to the approver and used in the key's name.

Required string length: 1 - 64

clientVersion

string

The CLI's version.

Required string length: 1 - 32

Response

The sign-in is open. Show userCode, open verificationUriComplete, then poll.

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

userCode

string

required

Eight letters in two groups of four, like BCDF-GHJK. Show it to the person; it is not a secret.

Pattern: ^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$

verificationUri

string<uri>

required

The console page to approve on. On the hosted service, https://console.phonebase.co/cli/authorize.

verificationUriComplete

string<uri>

required

The same page with the code filled in. Open this one when you can open a browser.

pollToken

string

required

pbcs_ followed by 43 characters. The ONLY way to collect the key. Keep it in memory, never print or log it; the service stores only its hash and cannot show it again.

intervalMs

integer

required

Wait at least this many milliseconds between polls. 5000 today. Faster answers 429 slow_down.

Required range: x >= 1000

expiresAt

string<date-time>

required

When the code stops working, 10 minutes after it was opened, approved or not.