AnkraDocs
Console

API reference · Access and identity

Email verification

2 operations of the Ankra Cloud API: Proving an email address - asking for a verification link and confirming its token.

Mail a new link that verifies the signed-in user's email address#

POST/v1/auth/email-verification
Operation
send_email_verification
Credentials
Portal session

For a user whose address is not verified yet (a password sign-up, an identity whose provider does not vouch for the address, an invited member): a new link goes to the address after the answer. It lives 24 hours and works once. At most 3 links are sent per user in 15 minutes; a further request is 429. A verified address answers 200 already_verified and sends nothing. 503 when this deployment cannot send email. The link's user.email_verification_requested audit event is written once the mail is out.

Responses

200The address is already verified; nothing was sent.application/json · EmailVerificationRequest

200 response fields
FieldTypeDescription
statusrequiredstringOne of sent, already_verified
emailrequiredstringThe address the link goes to.

202A new link is on its way.application/json · EmailVerificationRequest

202 response fields
FieldTypeDescription
statusrequiredstringOne of sent, already_verified
emailrequiredstringThe address the link goes to.
  • 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.
  • 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/auth/email-verification' \
  -b "ankracloud_session=$SESSION" \
  -H "X-CSRF-Token: $CSRF_TOKEN"

Verify an email address with the token from a verification link#

POST/v1/auth/email-verification/confirm
Operation
verify_email
Credentials
None (public)

Checks the token (looked up by its SHA-256; unused, unexpired, and sent to the address the user still has), marks the address verified, spends the token and every other open verification token of the user and records user.email_verified in the account's audit log. It opens no session. A refusal is a 400 problem with a stable reason: invalid_token, expired_token or used_token. Rate limited per client network (10 a minute).

Request bodyapplication/json · EmailVerificationConfirmation

Request body fields
FieldTypeDescription
tokenrequiredstringThe token query parameter of the verification link.

Responses

200The address is verified.application/json · EmailVerificationResult

200 response fields
FieldTypeDescription
emailrequiredstring
email_verifiedrequiredboolean
  • 400The token was refused; reason says which way.
  • 429Rate limited or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/auth/email-verification/confirm' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "string"
}'