API reference · Access and identity

Accounts and Ankra organisations

4 operations of the Ankra Cloud API: The accounts you act in and their link to Ankra platform organisations (platform.ankra.app is the primary identity).

The Ankra organisation this account belongs to#

GET/v1/account/organisation

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

link names the Ankra platform organisation the account is linked to (null when it is not) and members its members as the platform last confirmed them, with the owner seat marked. For the owner of an unlinked account of their own, candidates are the organisations they administer, confirmed by a sign-in with their Ankra account within the last hour, that have no Cloud account yet; for an account the Cloud workspace sync mirrors, that includes the organisation the sync made for it.

Responses

200The account's organisation.application/json · AccountOrganisation

200 response fields
Field	Type	Description
`link`required	OrganisationLink \| null
`organisation`required	PlatformOrganisation
`id`required	string (uuid)
`name`required	string
`linked_at`required	string (date-time)
`confirmed_at`required	string (date-time)
`has_owner_seat`required	boolean	The organisation holds the account's ownership (the account was created for it).
`is_owner_retained`required	boolean
`members`required	array of OrganisationMember
`user_id`required	string (uuid)
`email`required	string
`platform_role`required	string
`role`required	string	One of `owner`, `admin`, `member`, `viewer`
`is_owner`required	boolean
`is_stale`required	boolean
`confirmed_at`required	string (date-time)
`candidates`required	array of OrganisationMembership
`organisation`required	PlatformOrganisation
`id`required	string (uuid)
`name`required	string
`platform_role`required	string
`role`required	string	One of `admin`, `member`, `viewer`
`is_current`required	boolean
`is_stale`required	boolean
`confirmed_at`required	string (date-time)
`account_id`	string (uuid)	The organisation's Cloud account when you reach it; absent when opening the organisation creates it or needs a fresh sign-in.
`connected`required	boolean

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/organisation' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Link your account to an Ankra organisation (owner only)#

POST/v1/account/organisation

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

Links your own existing account to an Ankra platform organisation. You must be the account's owner, have signed in with your Ankra account within the last hour (403 with reason sign_in_with_ankra_required otherwise) and be an owner or admin of the organisation as the platform listed it; the organisation must have no Cloud account yet (409). The account keeps its owner, members, resources and billing; the organisation's members reach it from their next sign-in, and pending invitations are revoked because members now come from the organisation. Session-only. Audited as organisation.linked.

Request bodyapplication/json

Request body fields
Field	Type	Description
`organisation_id`required	string (uuid)

Responses

200The new link.application/json

200 response fields
Field	Type	Description
`link`required	OrganisationLink
`organisation`required	PlatformOrganisation
`id`required	string (uuid)
`name`required	string
`linked_at`required	string (date-time)
`confirmed_at`required	string (date-time)
`has_owner_seat`required	boolean	The organisation holds the account's ownership (the account was created for it).
`is_owner_retained`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).
409The resource's state does not allow this now.
503No capacity or address is free, or a host did not answer; try again later.
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/account/organisation' \
  -b "ankracloud_session=$SESSION" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "organisation_id": "00000000-0000-0000-0000-000000000000"
}'

The accounts you can act in#

GET/v1/accounts

Operation: list_accounts
Credentials: Portal session
Requires: Permission self

Your own account first, then the accounts of the Ankra platform organisations you belong to (as the platform listed them at your last sign-in with your Ankra account) and any account whose owner seat you hold, by name. active_account_id is the account your sessions act for now; organisations are the organisations the platform listed, each with the account_id you reach it as, or without one when opening it (POST /v1/accounts/active with organisation_id) creates its account or needs a fresh sign-in. Session-only.

Responses

200The accounts and organisations.application/json · AccountSwitcher

200 response fields
Field	Type	Description
`items`required	array of SwitchableAccount
`id`required	string (uuid)
`name`required	string
`role`required	string	One of `owner`, `admin`, `member`, `viewer`
`is_own_account`required	boolean
`is_active`required	boolean
`organisation`required	PlatformOrganisation \| null
`id`required	string (uuid)
`name`required	string
`platform_role`required	string	The role the platform gives you in the organisation; empty for your own account.
`is_stale`required	boolean	The last sign-in could not confirm this membership because the platform did not answer.
`is_owner_retained`required	boolean	You hold the owner seat although the platform no longer lists you; nobody else could take it.
`confirmed_at`required	string (date-time) \| null
`active_account_id`required	string (uuid)
`organisations`required	array of OrganisationMembership
`organisation`required	PlatformOrganisation
`id`required	string (uuid)
`name`required	string
`platform_role`required	string
`role`required	string	One of `admin`, `member`, `viewer`
`is_current`required	boolean
`is_stale`required	boolean
`confirmed_at`required	string (date-time)
`account_id`	string (uuid)	The organisation's Cloud account when you reach it; absent when opening the organisation creates it or needs a fresh sign-in.
`connected`required	boolean	Sign-in with an Ankra account follows platform organisations on this deployment.
`create_organisation_url`required	string (uri) \| null	The Ankra platform page that creates an organisation; null when this deployment is not connected to the platform. A new organisation is listed after the next sign-in with your Ankra account.

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

Act in another of your accounts, or open an Ankra organisation#

POST/v1/accounts/active

Operation: switch_account
Credentials: Portal session
Requires: Permission self

Every session of yours acts for this account from the next request on, with the role you hold there. Name it with account_id (your own account, or an organisation's account the platform lists you for; 404 for anything else), or name an Ankra platform organisation with organisation_id to open it: any organisation the platform listed for you at your last sign-in with your Ankra account, whose Cloud account is created when it has none (ADR 0011). An owner or admin of the organisation confirmed within the last hour takes the new account's owner seat; otherwise the first administrator of the organisation who signs in takes it. 403 with reason sign_in_with_ankra_required when your statement is stale or older than the account's link, 409 for an organisation the Cloud workspace sync created for another account or one whose account was created at the same moment (try again). A support session stays in its account (403). Session-only. Audited as account.switched in the account switched to, and organisation.account_opened when opening created it.

Request bodyapplication/json

Request body fields
Field	Type	Description
`account_id`	string (uuid)
`organisation_id`	string (uuid)	The Ankra platform organisation to open.

Responses

200The account your sessions act for now.application/json

200 response fields
Field	Type	Description
`account`required	SwitchableAccount
`id`required	string (uuid)
`name`required	string
`role`required	string	One of `owner`, `admin`, `member`, `viewer`
`is_own_account`required	boolean
`is_active`required	boolean
`organisation`required	PlatformOrganisation \| null
`id`required	string (uuid)
`name`required	string
`platform_role`required	string	The role the platform gives you in the organisation; empty for your own account.
`is_stale`required	boolean	The last sign-in could not confirm this membership because the platform did not answer.
`is_owner_retained`required	boolean	You hold the owner seat although the platform no longer lists you; nobody else could take it.
`confirmed_at`required	string (date-time) \| null

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.
409The resource's state does not allow this now.
503No capacity or address is free, or a host did not answer; try again later.
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/accounts/active' \
  -b "ankracloud_session=$SESSION" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "account_id": "00000000-0000-0000-0000-000000000000",
  "organisation_id": "00000000-0000-0000-0000-000000000000"
}'