API reference · Access and identity

Authentication

8 operations of the Ankra Cloud API: Customer sign-up, sign-in, sessions, invitations and support handoff.

Accept an invitation, create the user and sign them in#

POST/v1/auth/accept-invitation

Operation: accept_invitation
Credentials: None (public)

Request bodyapplication/json

Request body fields
Field	Type	Description
`invitation`required	string	The `aci_…` token from the signup link.
`password`required	string

Responses

201The user is created and signed in; the session cookies are set.application/json · IssuedSession

201 response fields
Field	Type	Description
`user`required	User
`id`required	string
`email`required	string
`name`	string	Set for users who signed up themselves.
`account_id`required	string
`role`required	string	One of `owner`, `admin`, `member`, `viewer`
`csrf_token`required	string
`expires_at`required	string (date-time)
`ended_sessions`	integer	Sign-in only: how many other sessions `end_other_sessions` ended.

400The request is invalid; detail says why.
404No such resource in the caller's account.
409The resource's state does not allow this now.
429Rate limited or the email is locked out.
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/auth/accept-invitation' \
  -H 'Content-Type: application/json' \
  -d '{
  "invitation": "string",
  "password": "string"
}'

End a support session and hand the environment back to staff#

POST/v1/auth/end-impersonation

Operation: end_impersonation
Credentials: Portal session

Responses

200The support session is ended and the cookies cleared.application/json

200 response fields
Field	Type	Description
`redirect`required	string	Where the staff browser goes next, e.g. `/admin/accounts/<account_id>`.

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

Look up an invitation by its token#

GET/v1/auth/invitation

Operation: look_up_invitation
Credentials: None (public)

Parameters

Parameters
Name	In	Type	Description
`invitation`required	query	string

Responses

200The pending invitation.application/json

200 response fields
Field	Type	Description
`email`required	string
`role`required	string	One of `owner`, `admin`, `member`, `viewer`
`account_name`required	string
`expires_at`required	string (date-time)

400The request is invalid; detail says why.
404No such resource in the caller's account.
429Rate limited or the email is locked out.
defaultAny other error, usually 500.

Example

bash

curl 'https://cloud.ankra.app/v1/auth/invitation?invitation=<invitation>'

Sign in and receive a session#

POST/v1/auth/login

Operation: log_in
Credentials: None (public)

Sets the ankracloud_session (HttpOnly) and ankracloud_csrf cookies. Rate limited per client address and per email.

A user with a second factor, or of an account that requires one, gets no session here: the answer is 200 with mfa_required: true, mfa_step and a short-lived signed challenge. verify is completed by POST /v1/auth/login/mfa with a code or a recovery code; enroll (the account requires a second factor and the user has none) by POST /v1/auth/login/mfa/enroll and then .../enroll/confirm. Audited as auth.login_mfa_required.

A user Ankra staff disabled gets 403 even with the right password.

Request bodyapplication/json · LoginRequest

Request body fields
Field	Type	Description
`email`required	string
`password`required	string
`end_other_sessions`	boolean	Sign the user out everywhere else once this sign-in succeeds; the response reports `ended_sessions`.

Responses

200Signed in, or the password was right and the second factor is next.application/json

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).
429Rate limited or the email is locked out.
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "string",
  "password": "string"
}'

End the session#

POST/v1/auth/logout

Operation: log_out
Credentials: Portal session, None (public)

Idempotent. Without a session, or with an expired one, it only clears the cookies. Ending a live session needs the CSRF header. With an identity provider configured it answers 200 { logout_url } instead of 204: the portal sends the browser there so the provider's own session ends too (single logout; on Auth0 that session is shared by every application on the same domain), and the provider returns to /login.

Responses

200Signed out; the cookies are cleared and the browser should follow logout_url.application/json

200 response fields
Field	Type	Description
`logout_url`required	string (uri)

204Signed out; the cookies are cleared.

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

The signed-in user, the CSRF token and the permissions of the role#

GET/v1/auth/me

Operation: get_current_user
Credentials: Portal session

Responses

200The signed-in user.application/json · CurrentUser

200 response fields
Field	Type	Description
`email_verified`required	boolean	Whether the user's email address is verified.
`email_verification_required`required	boolean	Whether the routes marked `x-ankra-verified-email` still refuse the user: the address is not verified and this deployment can send the link (`POST /v1/auth/email-verification`).
`user`required	User
`id`required	string
`email`required	string
`name`	string	Set for users who signed up themselves.
`account_id`required	string
`role`required	string	One of `owner`, `admin`, `member`, `viewer`
`csrf_token`required	string
`impersonation`required	Impersonation \| null
`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`
`expires_at`required	string (date-time)
`account_id`required	string
`permissions`required	array of string	One of `read`, `operate`, `members.manage`, `tokens.manage`, `billing.read`, `billing.manage`, `self`
`identities`required	array of LinkedIdentity	The identity provider identities linked to the user (empty without a provider).
`id`required	string
`provider`required	string	The issuer URL.
`provider_name`required	string	The upstream provider, from the subject's connection prefix: Google (`google-oauth2`), GitHub (`github`), Microsoft (`waad`, `windowslive`, `microsoft`), the provider's own accounts for `auth0` or no prefix (the display name, default "Ankra account"), else the prefix itself.
`subject_hint`required	string	The connection and the last characters of the subject; never the subject itself.
`linked_at`required	string (date-time)
`last_login_at`required	string (date-time) \| null

401Not signed in, or the credential is invalid or expired.
defaultAny other error, usually 500.

Example

bash

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

Create an account with yourself as its owner and get the link that verifies your email#

POST/v1/auth/signup

Operation: sign_up
Credentials: None (public)

Self-service signup. Creates the account (with the default quotas), its owner and EUR 249 of Cloud credit valid for 60 days from account creation in one transaction, and mails a link to the address that verifies it (POST /v1/auth/email-verification/confirm). It opens no session: the owner signs in with POST /v1/auth/login, and until the address is verified may not invite members, add a payment method or create billable resources (403 reason: email_unverified). The email is trimmed and lowercased. Without account_name the account is named after name. The answer is 202 with the same body whether the address is new or already has a user: that user gets a note saying someone tried to sign up with the address, and no second account is made, so the answer never says which addresses have accounts. Rate limited per client address (5 per minute); an address that already has a user counts towards that address's lockout. With coupon_code the code is redeemed for a new account (see POST /v1/account/coupons); a code that cannot be applied never fails the signup, and the answer does not say what happened to it (GET /v1/account/credits does).

Request bodyapplication/json · SignupRequest

Request body fields
Field	Type	Description
`name`required	string	Your name.
`email`required	string (email)
`password`required	string
`account_name`	string	Defaults to `name`.
`coupon_code`	string	A coupon code redeemed for the new account, for example from `/signup?coupon=WELCOME500`.

Responses

202The sign-up is accepted and a mail is on its way to the address.application/json · SignupAccepted

202 response fields
Field	Type	Description
`detail`required	string	The same sentence for every accepted sign-up.
`email`required	string	The address as it was stored: trimmed and lowercased.

400The request is invalid; detail says why.
429Rate limited or the email is locked out.
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/auth/signup' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "email": "string",
  "password": "string"
}'

Turn a support handoff code into the support session's cookies#

POST/v1/auth/support-handoff

Operation: redeem_support_handoff
Credentials: None (public)

The admin console answers POST /admin/v1/accounts/{id}/support-sessions with a handoff code and sends the staff browser to <portal>/support/handoff#code=…; that page posts the code here. The code is single use, expires after two minutes and mints the session's token on this origin, so the customer portal and the admin console never share cookies. Rate limited per client address.

Request bodyapplication/json

Request body fields
Field	Type	Description
`code`required	string	The `ash_…` handoff code.

Responses

200The support session is open on this origin; the cookies are set.application/json

200 response fields
Field	Type	Description
`redirect`required	string
`user`required	User
`id`required	string
`email`required	string
`name`	string	Set for users who signed up themselves.
`account_id`required	string
`role`required	string	One of `owner`, `admin`, `member`, `viewer`
`csrf_token`required	string
`impersonation`required	Impersonation
`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`
`expires_at`required	string (date-time)
`account_id`required	string
`expires_at`required	string (date-time)

400The request is invalid; detail says why.
401Not signed in, or the credential is invalid or expired.
429Rate limited or the email is locked out.
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/auth/support-handoff' \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "string"
}'