List usernames

GET /api/auth/username admin

Every username claimed on the deployment, paged by cursor.

Parameters

prefix string

Narrow to usernames starting with this. Query parameter.

cursor string

Continue from a previous page. Query parameter.

limit number

Page size. Defaults to the deployment list limit.

Returns

The page of usernames, and a cursor when there is more.

Request

curl "https://example.com/api/auth/username?limit=2" \
  -H "authorization: Bearer $TOKEN"

Response

{
  "usernames": ["ada", "grace"],
  "cursor": "01J2788XY98FDTA410C8S716CD"
}

Look up the identity behind a username

GET /api/auth/username/:username open

Resolves a username to the identity that claimed it. A username nobody has claimed answers 404 — which is the good answer to "is this available?", and the one a registration form is waiting for as somebody types.

Parameters

username string Required

Path parameter.

Returns

{ identity }, or 404 when the username is free.

Request

curl https://example.com/api/auth/username/ada

Response

{
  "identity": {
    "id": "01J2788XY98FDTA410C8S716CD",
    "kind": "member",
    "displayName": "Ada Lovelace"
  }
}

Check whether a username is taken

HEAD /api/auth/username/:username open

The same lookup without the body — the right call for an availability check, since it moves no identity data over the wire.

Parameters

username string Required

Path parameter.

Returns

200 when taken, 404 when free. No body either way.

Request

curl -I https://example.com/api/auth/username/ada

Response

{}

Begin username recovery

POST /api/auth/username/:username/recovery/challenge open

Sends a recovery challenge to whatever contact the identity behind the username has. Answers 200 whether or not the username exists, so it cannot be used to enumerate accounts.

Parameters

username string Required

Path parameter.

kind enum

The authentication payload the challenge is for.

Possible enum values

username

method enum

How the recovery should be delivered.

Possible enum values

verification
code

Returns

200, always.

Request

curl -X POST https://example.com/api/auth/username/ada/recovery/challenge \
  -H "content-type: application/json" \
  -d '{ "kind": "username", "method": "verification", "username": "ada" }'

Response

{
  "ok": true
}

Complete username recovery

POST /api/auth/username/:username/recovery open

Redeem the verification that POST …/recovery/challenge sent, and get a session back — this is how somebody who has lost their passphrase gets in far enough to set a new one.

Parameters

username string Required

Path parameter.

verification string Required

The token from the recovery challenge.

Returns

A session, with both cookies set.

Request

curl -X POST https://example.com/api/auth/username/ada/recovery \
  -H "content-type: application/json" \
  -d '{ "verification": "01J2788XY98FDTA410C8S716CD" }'

Response

{
  "identity": { "id": "01J2788XY98FDTA410C8S716CD", "kind": "member" },
  "identityToken": "eyJhbGciOi…",
  "refreshToken": "eyJhbGciOi…"
}

List phone numbers

GET /api/auth/phone admin

Every phone number registered on the deployment, paged by cursor.

Parameters

prefix string

Narrow to numbers starting with this. Query parameter.

cursor string

Continue from a previous page. Query parameter.

limit number

Page size. Defaults to the deployment list limit.

Returns

{ phones }.

Request

curl https://example.com/api/auth/phone \
  -H "authorization: Bearer $TOKEN"

Response

{
  "phones": ["+15550100", "+15550101"]
}

Look up the identity behind a phone number

GET /api/auth/phone/:phone open

Resolves a phone number to the identity that registered it. 404 when nothing claims it.

Parameters

phone string Required

Path parameter, URL-encoded.

Returns

{ identity }, or 404.

Request

curl https://example.com/api/auth/phone/%2B15550100

Response

{
  "identity": {
    "id": "01J2788XY98FDTA410C8S716CD",
    "kind": "member",
    "displayName": "Ada Lovelace"
  }
}

Check whether a phone number is registered

HEAD /api/auth/phone/:phone open

The same lookup with no body.

Parameters

phone string Required

Path parameter, URL-encoded.

Returns

200 when registered, 404 when not.

Request

curl -I https://example.com/api/auth/phone/%2B15550100

Response

{}

404 is the good answer

Listing is admin-only

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns