API reference · Access and identity

Support access

7 operations of the Ankra Cloud API: The customer's control over Ankra support access.

How elevated support sessions may be opened for this account#

GET/v1/account/support-access

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

Responses

200The standing decision.application/json · SupportAccessSetting

200 response fields
Field	Type	Description
`support_access`required	string	One of `consent_required`, `always_allowed`

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/account/support-access' \
  -b "ankracloud_session=$SESSION"

Change how elevated support sessions may be opened (owner only)#

PUT/v1/account/support-access

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

Session-only. consent_required (the default) makes staff ask for a consent code before every elevated session; always_allowed lets admin staff open one without asking. Read-only support sessions never need consent. Audited as support.access_changed.

Request bodyapplication/json · SupportAccessSetting

Request body fields
Field	Type	Description
`support_access`required	string	One of `consent_required`, `always_allowed`

Responses

200Changed.application/json · SupportAccessSetting

200 response fields
Field	Type	Description
`support_access`required	string	One of `consent_required`, `always_allowed`

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 PUT 'https://cloud.ankra.app/v1/account/support-access' \
  -b "ankracloud_session=$SESSION" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "support_access": "consent_required"
}'

The account's newest consent codes, open and closed (`next_cursor` is always null)#

GET/v1/account/support-consents

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

Responses

200Up to 50 consents, newest first.application/json · SupportConsentList

200 response fields
Field	Type	Description
`items`required	array of SupportConsent
`id`required	string
`created_by_email`required	string
`created_at`required	string (date-time)
`expires_at`required	string (date-time)
`used_at`required	string (date-time) \| null
`used_by_staff_email`required	string \| null
`revoked_at`required	string (date-time) \| null
`is_open`required	boolean	Not used, not revoked and not expired.
`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/account/support-consents' \
  -b "ankracloud_session=$SESSION"

Create a single-use consent code for one elevated support session#

POST/v1/account/support-consents

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

Session-only; a support session cannot call it. The code (XXXX-XXXX) is returned once and read to the staff member, who enters it when opening the elevated session. Valid 15 minutes to 24 hours (default one hour). Audited as support.consent_created.

Request bodyapplication/json · optional

Request body fields
Field	Type	Description
`duration_minutes`	integer

Responses

201The consent and its code.application/json

201 response fields
Field	Type	Description
`consent`required	SupportConsent
`id`required	string
`created_by_email`required	string
`created_at`required	string (date-time)
`expires_at`required	string (date-time)
`used_at`required	string (date-time) \| null
`used_by_staff_email`required	string \| null
`revoked_at`required	string (date-time) \| null
`is_open`required	boolean	Not used, not revoked and not expired.
`code`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).
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/account/support-consents' \
  -b "ankracloud_session=$SESSION" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "duration_minutes": 60
}'

Revoke an open consent code before staff use it#

DELETE/v1/account/support-consents/{id}

Operation: revoke_support_consent
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/account/support-consents/<id>' \
  -b "ankracloud_session=$SESSION" \
  -H "X-CSRF-Token: $CSRF_TOKEN"

The support sessions open in the account, newest first (`next_cursor` is always null)#

GET/v1/account/support-sessions

Operation: list_support_sessions
Credentials: API token, Portal session
Requires: Permission read

Responses

200Every unexpired support session, with the staff member, mode and reason.application/json · SupportSessionList

200 response fields
Field	Type	Description
`items`required	array of SupportSession
`id`required	string
`acting_as_email`required	string	The account user the staff member acts as.
`staff_email`required	string
`staff_name`required	string
`reason`required	string
`mode`required	string	`read_only` sessions change nothing and read no credential (database passwords, object storage keys, the console, instance metadata, payment methods). `elevated` sessions act like the customer, except that no support session manages API tokens, members, payment methods or support consents.One of `read_only`, `elevated`
`created_at`required	string (date-time)
`expires_at`required	string (date-time)
`last_seen_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/account/support-sessions' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

End a support session now#

DELETE/v1/account/support-sessions/{id}

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

Session-only; the staff browser is signed out of the account at once. Audited as support.session_ended by the customer.

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/account/support-sessions/<id>' \
  -b "ankracloud_session=$SESSION" \
  -H "X-CSRF-Token: $CSRF_TOKEN"