API reference · Access and identity

API tokens, members and sessions

12 operations of the Ankra Cloud API: API tokens, members, invitations and sessions.

List API tokens, newest first (revoked tokens are not listed)#

GET/v1/api-tokens

Operation: list_api_tokens
Credentials: Portal session
Requires: Permission tokens.manage

Session-only, like every route under /v1/api-tokens and /v1/members: an API token gets 403 here, so a leaked token can neither mint another nor invite anyone.

Parameters

Parameters
Name	In	Type	Description
`cursor`	query	string	The `next_cursor` of the previous page.

Responses

200A page of API tokens.application/json · ApiTokenList

200 response fields
Field	Type	Description
`items`required	array of ApiToken
`id`required	string
`name`required	string
`prefix`required	string	The first 8 characters of the token (`act_` plus 4).
`scope`required	string	`read` (any read the role allows, no writes), `read_write` (everything the role allows), or a comma-separated list of permissions from read, operate, billing.read, billing.manage and self, stored in that order; a list always includes read and self. tokens.manage and members.manage cannot be granted.
`created_by_email`required	string
`created_at`required	string (date-time)
`last_used_at`required	string (date-time) \| null
`expires_at`required	string (date-time)
`next_cursor`required	string \| null	Pass as `?cursor=` for the next page; null on the last page.

400The request is invalid; detail says why.
401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
defaultAny other error, usually 500.

Example

bash

curl 'https://cloud.ankra.app/v1/api-tokens' \
  -b "ankracloud_session=$SESSION"

Create an API token#

POST/v1/api-tokens

Operation: create_api_token
Credentials: Portal session
Requires: Permission tokens.manage

The plaintext token is returned only here. A support session gets 403.

Request bodyapplication/json

Request body fields
Field	Type	Description
`name`required	string
`scope`required	string	`read` (any read the role allows, no writes), `read_write` (everything the role allows), or a comma-separated list of permissions from read, operate, billing.read, billing.manage and self, stored in that order; a list always includes read and self. tokens.manage and members.manage cannot be granted.
`expires_at`	string (date-time)	In the future and at most 365 days away; 90 days when omitted. An explicit null is refused with 400.

Responses

201The token.application/json

201 response fields
Field	Type	Description
`api_token`required	ApiToken
`id`required	string
`name`required	string
`prefix`required	string	The first 8 characters of the token (`act_` plus 4).
`scope`required	string	`read` (any read the role allows, no writes), `read_write` (everything the role allows), or a comma-separated list of permissions from read, operate, billing.read, billing.manage and self, stored in that order; a list always includes read and self. tokens.manage and members.manage cannot be granted.
`created_by_email`required	string
`created_at`required	string (date-time)
`last_used_at`required	string (date-time) \| null
`expires_at`required	string (date-time)
`token`required	string	`act_` plus 32 random bytes, base64url.

400The request is invalid; detail says why.
401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/api-tokens' \
  -b "ankracloud_session=$SESSION" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "scope": "read,operate,self"
}'

Revoke an API token#

DELETE/v1/api-tokens/{id}

Operation: revoke_api_token
Credentials: Portal session
Requires: Permission tokens.manage

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

204Revoked.

401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
defaultAny other error, usually 500.

Example

bash

curl -X DELETE 'https://cloud.ankra.app/v1/api-tokens/<id>' \
  -b "ankracloud_session=$SESSION" \
  -H "X-CSRF-Token: $CSRF_TOKEN"

List the account's members, oldest first#

GET/v1/members

Operation: list_members
Credentials: Portal session
Requires: Permission read

Parameters

Parameters
Name	In	Type	Description
`cursor`	query	string	The `next_cursor` of the previous page.
`limit`	query	integer	Page size; the server applies its default and maximum.

Responses

200A page of members.application/json · MemberList

200 response fields
Field	Type	Description
`items`required	array of Member
`id`required	string
`email`required	string
`role`required	string	One of `owner`, `admin`, `member`, `viewer`
`created_at`required	string (date-time)
`last_login_at`required	string (date-time) \| null
`is_current_user`required	boolean
`next_cursor`required	string \| null	Pass as `?cursor=` for the next page; null on the last page.

400The request is invalid; detail says why.
401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
defaultAny other error, usually 500.

Example

bash

curl 'https://cloud.ankra.app/v1/members' \
  -b "ankracloud_session=$SESSION"

Change a member's role#

PATCH/v1/members/{id}

Operation: change_member_role
Credentials: Portal session
Requires: Permission members.manage

403 for the owner, and for a support session.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Request bodyapplication/json

Request body fields
Field	Type	Description
`role`required	string	Nobody can be made owner through the API.One of `admin`, `member`, `viewer`

Responses

200The member.application/json

200 response fields
Field	Type	Description
`member`required	Member
`id`required	string
`email`required	string
`role`required	string	One of `owner`, `admin`, `member`, `viewer`
`created_at`required	string (date-time)
`last_login_at`required	string (date-time) \| null
`is_current_user`required	boolean

400The request is invalid; detail says why.
401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
defaultAny other error, usually 500.

Example

bash

curl -X PATCH 'https://cloud.ankra.app/v1/members/<id>' \
  -b "ankracloud_session=$SESSION" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": "admin"
}'

Remove a member with their sessions and API tokens#

DELETE/v1/members/{id}

Operation: remove_member
Credentials: Portal session
Requires: Permission members.manage

403 for the owner, and for a support session; 409 for yourself.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

204Removed.

401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
409The resource's state does not allow this now.
defaultAny other error, usually 500.

Example

bash

curl -X DELETE 'https://cloud.ankra.app/v1/members/<id>' \
  -b "ankracloud_session=$SESSION" \
  -H "X-CSRF-Token: $CSRF_TOKEN"

List pending invitations (`next_cursor` is always null)#

GET/v1/members/invitations

Operation: list_invitations
Credentials: Portal session
Requires: Permission members.manage

Responses

200Every pending invitation.application/json · InvitationList

200 response fields
Field	Type	Description
`items`required	array of Invitation
`id`required	string
`email`required	string
`role`required	string	One of `owner`, `admin`, `member`, `viewer`
`invited_by_email`required	string
`created_at`required	string (date-time)
`expires_at`required	string (date-time)
`next_cursor`required	string \| null	Pass as `?cursor=` for the next page; null on the last page.

401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
defaultAny other error, usually 500.

Example

bash

curl 'https://cloud.ankra.app/v1/members/invitations' \
  -b "ankracloud_session=$SESSION"

Invite someone to the account#

POST/v1/members/invitations

Operation: invite_member
Credentials: Portal session
Requires: Permission members.manage

409 when the email is already a member of this account. A support session gets 403.

Request bodyapplication/json

Request body fields
Field	Type	Description
`email`required	string (email)
`role`required	string	Nobody can be made owner through the API.One of `admin`, `member`, `viewer`

Responses

201The invitation and its single-use signup link (valid 7 days).application/json

201 response fields
Field	Type	Description
`invitation`required	Invitation
`id`required	string
`email`required	string
`role`required	string	One of `owner`, `admin`, `member`, `viewer`
`invited_by_email`required	string
`created_at`required	string (date-time)
`expires_at`required	string (date-time)
`token`required	string	The `aci_…` invitation token.
`signup_path`required	string

400The request is invalid; detail says why.
401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
409The resource's state does not allow this now.
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/members/invitations' \
  -b "ankracloud_session=$SESSION" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "string",
  "role": "admin"
}'

Revoke a pending invitation#

DELETE/v1/members/invitations/{id}

Operation: revoke_invitation
Credentials: Portal session
Requires: Permission members.manage

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

204Revoked.

401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
defaultAny other error, usually 500.

Example

bash

curl -X DELETE 'https://cloud.ankra.app/v1/members/invitations/<id>' \
  -b "ankracloud_session=$SESSION" \
  -H "X-CSRF-Token: $CSRF_TOKEN"

The caller's unexpired sessions, newest first (`next_cursor` is always null)#

GET/v1/sessions

Operation: list_sessions
Credentials: API token, Portal session
Requires: Permission self

Responses

200Every session of the caller.application/json · SessionList

200 response fields
Field	Type	Description
`items`required	array of Session
`id`required	string
`created_at`required	string (date-time)
`last_seen_at`required	string (date-time)
`expires_at`required	string (date-time)
`is_current`required	boolean
`is_support_session`required	boolean
`staff_email`required	string \| null	Null unless `is_support_session`.
`next_cursor`required	string \| null	Pass as `?cursor=` for the next page; null on the last page.

401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
defaultAny other error, usually 500.

Example

bash

curl 'https://cloud.ankra.app/v1/sessions' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

End one of the caller's sessions#

DELETE/v1/sessions/{id}

Operation: revoke_session
Credentials: API token, Portal session
Requires: Permission self

Ending the current session also clears its cookies.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

204Ended.

401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
defaultAny other error, usually 500.

Example

bash

curl -X DELETE 'https://cloud.ankra.app/v1/sessions/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

End every session of the user except the one making the call#

POST/v1/sessions/revoke-others

Operation: revoke_other_sessions
Credentials: API token, Portal session
Requires: Permission self

Responses

200How many sessions were ended.application/json

200 response fields
Field	Type	Description
`revoked`required	integer

401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/sessions/revoke-others' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"