Skip to content

Operation Not Available While Impersonating

URI: https://docs.ankatech.co/errors/impersonation-operation-forbidden
HTTP Status: 403 Forbidden

When you see this

The caller is acting under a support-access impersonation session and took a route that is withheld from such a session by design. This is not an authorization failure: the operator holds the scope and is inside the tenant boundary. The refusal is raised as the handler's first statement, so nothing downstream runs and no state changes.

Common Causes

  • A key-plane route that moves key material in or destroys it: import-key, import-keystore, import-keystore/analyze, mark-for-destruction and cancel-destruction. Key creation and rotation stay permitted.
  • A tenant-plane route that establishes access outliving the consent window — the durable-access set, which spans the user, actor, credential, role, identity-provider, email-domain and support-access controllers.
  • The impersonation claim could not be read at all: the check is fail-closed, so an unreadable claim is treated as impersonation.

Response Example

{
  "type": "https://docs.ankatech.co/errors/impersonation-operation-forbidden",
  "title": "Operation Not Available While Impersonating",
  "status": 403,
  "detail": "This operation is not available while acting on behalf of a tenant.",
  "instance": "/api/v3/admin/tenants/7c9e6679-7425-40de-944b-e07fc1f90ae7/keys/import-key",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details.

Branch on type, not on the status: the generic forbidden type reads as a missing scope and would send an operator to widen a role, which cannot help here. Every refusal body is identical apart from instance, and names no key, tenant, operator or window. Both denied sets bind on SaaS deployments only — on a customer-operated deployment the operator is the deployment's own owner, and the routes remain permitted there.

How to Resolve

  1. Ask the tenant to perform the operation under their own credentials — the remedy belongs to whoever owns the tenant, not to the support session.
  2. For a key import or destruction, the tenant's own administrator must issue it; support impersonation can still create and rotate keys.
  3. If the operation is genuinely part of support, reconsider whether it belongs inside a bounded consent window at all — a durable change outlives the window by definition, which is why it is refused rather than audited after the fact.

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