API reference · Access and identity
Linked identities
3 operations of the Ankra Cloud API: The signed-in user's linked sign-in identities.
List the identity provider identities you sign in with#
/v1/account/identities- Operation
list_account_identities- Credentials
- API token, Portal session
- Requires
- Permission
self
The signed-in user's linked identities (Google, Microsoft, GitHub or the provider's own accounts), oldest first; the same list GET /v1/auth/me carries in identities. Empty when no identity provider was ever used.
Responses
200The linked identities, at most 50; never paged, and next_cursor is always null.application/json · LinkedIdentityList
| Field | Type | Description |
|---|---|---|
itemsrequired | array of LinkedIdentity | |
idrequired | string | |
providerrequired | string | The issuer URL. |
provider_namerequired | 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_hintrequired | string | The connection and the last characters of the subject; never the subject itself. |
linked_atrequired | string (date-time) | |
last_login_atrequired | string (date-time) | null | |
next_cursorrequired | 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_credentialson 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. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/account/identities' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Unlink one of your sign-in identities#
/v1/account/identities/{id}- Operation
unlink_account_identity- Credentials
- Portal session
- Requires
- Permission
self
The provider account can no longer sign in as you. Your last way to sign in is never removed: a user without a password keeps their only identity (409). Session-only; a support session is refused (403). The unlink and its audit event (auth.identity_unlink) are stored together.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
200The identity was unlinked.application/json
| Field | Type | Description |
|---|---|---|
identityrequired | LinkedIdentity | |
idrequired | string | |
providerrequired | string | The issuer URL. |
provider_namerequired | 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_hintrequired | string | The connection and the last characters of the subject; never the subject itself. |
linked_atrequired | string (date-time) | |
last_login_atrequired | string (date-time) | null |
- 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_credentialson 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
curl -X DELETE 'https://cloud.ankra.app/v1/account/identities/<id>' \
-b "ankracloud_session=$SESSION" \
-H "X-CSRF-Token: $CSRF_TOKEN"Start linking an identity provider identity to yourself#
/v1/account/identities/{provider}/link- Operation
link_account_identity- Credentials
- Portal session
- Requires
- Permission
self
Starts linking an identity of one of this deployment's providers to the signed-in user, so they can sign in
with it from then on. Answers the provider URL to send the browser to and sets the ankracloud_oidc_link
cookie (HttpOnly, 10 minutes), a signed challenge that names the user. The provider always asks who the person
is, and returns to the ordinary callback (GET /v1/auth/oidc/callback), which recognises the link by that
cookie and the state and then links the identity to the user the browser's session belongs to, when that is
the user who started the link. The identity's email plays no part in choosing the user, no session is opened
or changed, and the link is audited as account.identity_linked. When the provider vouches for the identity's
address and it is the user's own, that address counts as verified from then on. The callback answers 302 to
return_to with identity_link=linked, already_linked (you hold this identity already), taken (it signs
in another user; it is never moved), signed_out (the browser is no longer signed in as the user who started
the link), expired, email_unverified, email_missing, unavailable or failed. Session-only; a support
session is refused (403). Rate limited per client address like the sign-in routes.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
providerrequired | path | string | The name of one of the providers GET /v1/auth/oidc lists. |
Request bodyapplication/json · LinkIdentityRequest · optional
| Field | Type | Description |
|---|---|---|
connection | string | Goes straight to one of the provider's connections (GET /v1/auth/oidc); 400 when it is not offered. |
return_to | string | The portal path the browser lands on afterwards; /settings when absent or not a same-origin path. |
Responses
200Where to send the browser; the link challenge cookie is set.application/json · LinkIdentityStart
| Field | Type | Description |
|---|---|---|
authorization_urlrequired | string (uri) | The provider URL to send the browser to. |
- 400The request is invalid;
detailsays 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_credentialson 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.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - 503No capacity or address is free in the zone right now (
reason: capacity_unavailable, with availability wording indetail), or a host did not answer; try another plan or zone, or try again later. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/account/identities/<provider>/link' \
-b "ankracloud_session=$SESSION" \
-H "X-CSRF-Token: $CSRF_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"connection": "string",
"return_to": "string"
}'