Skip to content

Integration Delegation Required

URI: https://docs.ankatech.co/errors/integration-delegation-required
HTTP Status: 403 Forbidden

When you see this

A tenant administrator tried to change one of the tenant's integrations on a customer-operated deployment (private cloud or on-premise), and the platform operator has not delegated that integration family to the tenant's own administrators.

On a customer-operated deployment the platform operator decides, per tenant and per integration family, whether the tenant's administrators may change that family's configuration. Five families are delegable:

Family Tenant operations it covers
hsm-cloud-kms The tenant's own key-protection backend (bindByok, testByok, validateTenantByokBackend, updateByokCredential, replaceByokDriverDeclaration, deleteByok) and its key custody moves (createTenantKeyCustodyMove, replaceTenantKeyCustodyMoveDestination, replaceTenantKeyCustodyMoveSchedule, cancelTenantKeyCustodyMove, abortTenantKeyCustodyMove, rollbackTenantKeyCustody)
email-notifications The tenant's delivery providers (declareNotificationProvider, validateNotificationProviderConfig, replaceNotificationProviderConfig, testNotificationProvider, enableNotificationProvider, disableNotificationProvider, replaceNotificationProviderCredential, deleteNotificationProviderCredential)
security-event-forwarding The tenant's event-forwarding destinations (createDestination, replaceDestination, deleteDestination)
workload-identity-federation The tenant's trusted workload issuers and issuer bindings (createTenantTrustedIssuer, replaceTenantTrustedIssuer, deleteTenantTrustedIssuer, enableTenantTrustedIssuer, disableTenantTrustedIssuer, validateTenantTrustedIssuer, testTenantTrustedIssuer, createTenantActorIssuerBinding, deleteTenantActorIssuerBinding, createTenantWorkloadIssuerBinding)
identity-federation The tenant's identity providers and their rules (createIdp, validateIdp, testIdp, enableIdp, disableIdp, revokeIdp, createMapping, deleteMapping, createAdmissionRule, deleteAdmissionRule, createDomainGuard, deleteDomainGuard, createEmailDomain, deleteEmailDomain)

Only writes are refused. Reading the tenant's configuration of a family is never gated, so a tenant whose delegation was withdrawn still sees its configuration, unchanged and inert. Nothing was changed by the refused request.

On a deployment ANKATech operates (SaaS, Dedicated SaaS) there is no delegation: this refusal is never returned, and the tenant's edition and entitlements decide.

The body is the same for every tenant and every family: it names neither the tenant nor the family, and it does not say which other families are delegated.

Common Causes

  • The platform operator never delegated the family to this tenant.
  • The delegation was withdrawn after the tenant configured the integration.
  • A platform administrator used a tenant-plane route for the platform tenant itself. The platform tenant is judged like any other tenant on these routes; the platform's own configuration is changed through the platform-plane operations.

Response Example

{
  "type": "https://docs.ankatech.co/errors/integration-delegation-required",
  "title": "Integration Delegation Required",
  "status": 403,
  "detail": "This integration family has not been delegated to tenant administrators on this deployment. Only the platform operator can configure it.",
  "instance": "/api/v3/admin/tenants/2c8f5a31-7b04-4d9e-a1c6-3f80e5b2d947/notification/providers",
  "timestamp": 1763112600,
  "extensions": {
    "requestId": "7a3d9c1e-5b28-4f64-8e07-c2b6a1d4f953"
  }
}

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

How to Resolve

  1. Ask the platform operator of the deployment to delegate the integration family to your tenant.
  2. The platform operator reads the tenant's delegations with GET /api/v3/admin/platform/tenants/{tenantId}/integration-delegations (operation getTenantIntegrationDelegations) and sets them with PUT /api/v3/admin/platform/tenants/{tenantId}/integration-delegations (operation replaceTenantIntegrationDelegations).
  3. Retry the change once the family is delegated. Alternatively, the platform operator makes the change on the tenant's behalf from the platform plane.

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