API reference · Access and identity

Ankra Platform workspace sync

4 operations of the Ankra Cloud API: Workspace organisation sync and server-only delegated membership.

Workspace organisation mapping and membership sync status#

GET/v1/account/platform

Operation: get_platform_workspace_sync
Credentials: Portal session
Requires: Permission read

Responses

200Current sync state, last success, revision and member count. A not_configured state carries no mapping.application/json

200 response fields
Field	Type	Description
`state`required	string	One of `not_configured`, `pending`, `synced`, `failed`, `stale`
`workspace_id`	string (uuid)
`name`	string
`organisation_id`	string (uuid) \| null
`revision`	integer
`synced_revision`	integer
`synced_at`	string (date-time) \| null
`member_count`	integer
`last_error`	string

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

Server-only current-member credential exchange#

GET/v1/account/platform/credential

Operation: get_platform_workspace_credential
Credentials: Portal session
Requires: Permission read

Requires a customer session and the private X-Ankra-Cloud-BFF-Token header. API tokens and support sessions are refused. The delegated credential is short lived and must never be exposed to the browser.

Parameters

Parameters
Name	In	Type	Description
`X-Ankra-Cloud-BFF-Token`required	header	string

Responses

200Private no-store credential for the authenticated member only.application/json

200 response fields
Field	Type	Description
`organisation_id`required	string (uuid)
`workspace_id`required	string (uuid)
`user_id`required	string (uuid)
`role`required	string	One of `owner`, `admin`, `member`, `viewer`
`platform_user_id`required	string
`token`required	string
`valid_until`required	string (date-time)

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).
409Membership sync is pending or stale.
defaultAny other error, usually 500.

Example

bash

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

Assigned organisation and cluster domains in the linked Platform workspace#

GET/v1/account/platform/domains

Operation: get_platform_workspace_domains
Credentials: Portal session
Requires: Permission read

Session-only read using the current member's delegated identity. Pending membership returns 409; an unavailable inventory never returns an empty list. API tokens and support impersonation are refused. DNS authority remains in Platform.

Responses

200Assigned hostnames and their authoritative provisioning states.application/json

200 response fields
Field	Type	Description
`organisation_id`required	string (uuid)
`zone`required	object
`fqdn`required	string
`state`required	string
`clusters`required	array of object
`cluster_id`required	string (uuid)
`cluster_name`required	string
`fqdn`required	string
`state`required	string

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).
409Workspace membership is pending or stale.
defaultAny other error, usually 500.

Example

bash

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

Queue a membership sync retry#

POST/v1/account/platform/sync

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

Session-only administrator action. Cloud remains authoritative; this never accepts a target organisation or member list.

Responses

202Queued for the background reconciler.application/json

202 response fields
Field	Type	Description
`state`required	"queued"

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/platform/sync' \
  -b "ankracloud_session=$SESSION" \
  -H "X-CSRF-Token: $CSRF_TOKEN"