Account and Personal keys

Your profile, two-factor sign-in, sessions, Personal keys, the CLI device login and the sign-up checks.

These routes act on you, the person the key belongs to, not on an Organization. Making, listing and revoking Personal keys, two-factor changes, revoking a session and changing your sign-in email need a signed-in console session: a Personal key is refused there with 403, except that a key may delete itself (what cloudgate logout does).

Every request goes to https://cloudgate.octabyte.app/backend on the Hosted instance, or to your console address followed by /backend when you self-host. Send a Personal key in x-api-key and the Organization in x-organization-id; Authentication shows how to make the key, and Errors explains every refusal. The examples setCLOUDGATE_KEY and CLOUDGATE_ORG_ID in the shell first. To do the same in the console, read Personal keys in the user guide.

You and your keys

Get your profile

GET/users/me

Who can call it: You: any signed-in person, with a Personal key or a console session.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid. The error body.

curl https://cloudgate.octabyte.app/backend/users/me \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update your profile

PATCH/users/me

Who can call it: You. Changing the sign-in email needs a signed-in console session; a Personal key is refused with 403.

Request body

Field	Type	Notes
`firstName`	string	1 to 255 characters.
`lastName`	string	Up to 255 characters.
`email`	string (email)	Up to 255 characters. Matches `^(?!\.)(?!.\.\.)([A-Za-z0-9_'+\-\.])[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`.
`currentPassword`	string	Not empty.
`image`	string (uri) or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Sent with a Personal key where a console session is needed. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/users/me \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "firstName": "example",
    "lastName": "example",
    "email": "ada@northwind.dev"
  }'

Show who a key belongs to

GET/users/me/whoami

Who can call it: You: any signed-in person, with a Personal key or a console session.

Responses

200 OK: Who this request is made as: the email, the Organization it acts in, and the Personal key it carries (null for a console session). Answers only about the key the request was made with, never another.
Refusals: 401 No key, or the key is not valid. The error body.

Fields of the `200` answer
Field	Type	Notes
`email`always	string
`organization`always	object or null
`organization.id`always	string
`organization.name`always	string
`key`always	object or null
`key.id`always	string
`key.name`always	string or null
`key.start`always	string or null
`key.expiresAt`always	string or null

curl https://cloudgate.octabyte.app/backend/users/me/whoami \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Turn on two-factor sign-in

POST/users/me/2fa/enable

Who can call it: You, from a signed-in console session only: a Personal key is refused with 403.

Request body

Field	Type	Notes
`password`required	string	Not empty.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Sent with a Personal key where a console session is needed. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/users/me/2fa/enable \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "password": "<secret>"
  }'

Verify a two-factor code

POST/users/me/2fa/verify

Who can call it: You, from a signed-in console session only: a Personal key is refused with 403.

Request body

Field	Type	Notes
`code`required	string	Not empty.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Sent with a Personal key where a console session is needed. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/users/me/2fa/verify \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "code": "example"
  }'

Turn off two-factor sign-in

POST/users/me/2fa/disable

Who can call it: You, from a signed-in console session only: a Personal key is refused with 403.

Request body

Field	Type	Notes
`password`required	string	Not empty.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Sent with a Personal key where a console session is needed. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/users/me/2fa/disable \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "password": "<secret>"
  }'

List your sessions

GET/users/me/sessions

Who can call it: You: any signed-in person, with a Personal key or a console session.

Responses

200 OK: The caller's own sessions. Deliberately carries no session token — the token is the credential, and revocation is by id.
Refusals: 401 No key, or the key is not valid. The error body.

Fields of the `200` answer
Field	Type	Notes
`[].id`always	string
`[].userId`always	string
`[].userAgent`	string or null
`[].ipAddress`	string or null
`[].createdAt`always	string (date-time)
`[].expiresAt`always	string (date-time)

curl https://cloudgate.octabyte.app/backend/users/me/sessions \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List your Personal keys

GET/users/me/api-keys

Who can call it: You, from a signed-in console session only: a Personal key is refused with 403.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Sent with a Personal key where a console session is needed. The error body.

curl https://cloudgate.octabyte.app/backend/users/me/api-keys \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Create a Personal key

POST/users/me/api-keys

Who can call it: You, from a signed-in console session only: a Personal key is refused with 403.

Request body

Field	Type	Notes
`name`required	string	1 to 255 characters.
`prefix`	string	Up to 64 characters.
`expiresIn`	integer	At least 0. More than true.

Responses

201 Created: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Sent with a Personal key where a console session is needed. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/users/me/api-keys \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "Ada Lovelace"
  }'

Delete a Personal key

DELETE/users/me/api-keys/{id}

Who can call it: You, from a signed-in console session; a Personal key may delete only itself.

Parameters

Name	In	Type	Notes
`id`required	path	string	The user's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Sent with a Personal key where a console session is needed; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE https://cloudgate.octabyte.app/backend/users/me/api-keys/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Revoke a session

POST/users/me/sessions/revoke

Who can call it: You, from a signed-in console session only: a Personal key is refused with 403.

Request body

Field	Type	Notes
`sessionId`required	string	Not empty.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Sent with a Personal key where a console session is needed. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/users/me/sessions/revoke \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "sessionId": "jouKjCrujNdcqEeKJNcoP"
  }'

Device login

Start a device login

POST/auth/device/code

Who can call it: Public: no key needed.

Request body

A object.

Responses

200 OK: Starts a CLI login: a code for the person to approve at /device, and the device code the CLI polls with. Takes no fields; in particular no user, so a code is bound only to whoever approves it.
Refusals: 400 Validation failed; details names each field. The error body.

Fields of the `200` answer
Field	Type	Notes
`deviceCode`always	string
`userCode`always	string
`interval`always	number
`expiresIn`always	number

curl -X POST https://cloudgate.octabyte.app/backend/auth/device/code \
  -H "content-type: application/json" \
  -d '{}'

Poll a device login for its key

POST/auth/device/token

Who can call it: Public: no key needed.

Request body

Field	Type	Notes
`deviceCode`required	string	Not empty.
`name`	string	1 to 100 characters.
`replaces`	string	1 to 200 characters.

Responses

200 OK: The CLI's poll. Once the code is approved, a Personal key ending 90 days after login, answered once; until then a 400 whose code is AUTHORIZATION_PENDING, SLOW_DOWN, EXPIRED_TOKEN, ACCESS_DENIED or INVALID_GRANT.
Refusals: 400 Validation failed; details names each field. The error body.

Fields of the `200` answer
Field	Type	Notes
`key`always	string
`keyId`always	string
`expiresAt`always	string

curl -X POST https://cloudgate.octabyte.app/backend/auth/device/token \
  -H "content-type: application/json" \
  -d '{
    "deviceCode": "example"
  }'

GET/auth/sign-up-open

open is whether an uninvited sign-up is accepted now; state says which of the four SignUpStates that is, because the screen says different things for each: "Set up this instance" and "Already set up" when Self-hosted, "Not open yet" and the public form when Hosted.

Who can call it: Public: no key needed.

Responses

200 OK: The result, as JSON.

curl https://cloudgate.octabyte.app/backend/auth/sign-up-open

Check whether password reset works

GET/auth/password-reset-open

Who can call it: Public: no key needed.

Responses

200 OK: The result, as JSON.

curl https://cloudgate.octabyte.app/backend/auth/password-reset-open

Preview an invitation

GET/auth/invitations/{id}

Who can call it: Public: no key needed.

Parameters

Name	In	Type	Notes
`id`required	path	string	The id.

Responses

200 OK: The result, as JSON.
Refusals: 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/auth/invitations/RAU6yAYUXFRdXdPLyLoPC

Something missing or wrong on this page? Email support@octabyte.io, or start a free trial and try it in the console.

You and your keys

Get your profile

Responses

Update your profile

Request body

Responses

Show who a key belongs to

Responses

Turn on two-factor sign-in

Request body

Responses

Verify a two-factor code

Request body

Responses

Turn off two-factor sign-in

Request body

Responses

List your sessions

Responses

List your Personal keys

Responses

Create a Personal key

Request body

Responses

Delete a Personal key

Parameters

Responses

Revoke a session

Request body

Responses

Device login

Start a device login

Request body

Responses

Poll a device login for its key

Request body

Responses

Sign-up checks

Check whether sign-up is open

Responses

Check whether password reset works

Responses

Preview an invitation

Parameters

Responses