Skip to content

Email Address Does Not Match

URI: https://docs.ankatech.co/errors/federated-link-claim-mismatch
HTTP Status: 422 Unprocessable Entity

When you see this

The email address declared in the link intent is not the address the target account already uses. Such an intent could never be consumed: the bind leg reaches an intent only through the account resolved from the address the identity provider asserts, so an intent declared against a different address is unreachable by construction.

The refusal is raised on the declare leg of federated account linking, POST /api/v3/admin/tenants/{tenantId}/users/{userId}/federated-link-intent. Nothing was written: no intent exists, no notification was sent, and the target account is unchanged.

Accepting it would be worse than refusing it. The console would show "link pending" for the whole authorization window, the account holder would be notified, and nothing would ever happen — and the operator's evidence that the authorization exists would look identical to one that works.

This refusal names the mismatch rather than hiding it. The caller is already authorized on this tenant and can read the account's address, so concealing it would only hide a typo from the one person able to correct it.

Common Causes

  • A typo in the declared email address.
  • The account's address was changed after the value was copied.
  • The address of a different account was pasted into the request.

Response Example

{
  "type": "https://docs.ankatech.co/errors/federated-link-claim-mismatch",
  "title": "Email Address Does Not Match",
  "status": 422,
  "detail": "The email address must be the one this account already uses. A link is only ever consumed by an assertion carrying that address, so a different value would never take effect.",
  "instance": "/api/v3/admin/tenants/2f1c9d84-6b2e-4d3a-9f57-0a1b2c3d4e5f/users/8c4f1a02-77d5-4e19-b3ac-51e6d9f0a742/federated-link-intent",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. This is an Admin API body, so the correlation identifier is extensions.requestId; see Error Index & Overview.

How to Resolve

  1. Read the target account's own email address in the console.
  2. Declare the intent with that address, exactly.
  3. If the account's address is itself wrong, correct it on the account first, then declare the intent.

For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.