Skip to content

Exchange Grant Actor Not Participant

URI: https://docs.ankatech.co/errors/exchange-grant-actor-not-participant
HTTP Status: 422 Unprocessable Content

When you see this

A Capability Grant of a Cryptographic Exchange would name an actor that does not belong to either endpoint of the Exchange. Nothing was written.

An Exchange authorizes the applications at its ends. Its grants may name only an actor of its origin application or of its destination application; an actor of any other application, or an actor with no application, cannot hold them. An external counterparty endpoint has no actors of the tenant, so in an OUTBOUND or INBOUND Exchange the grants name actors of the one internal endpoint.

The refusal answers two operations:

  • createExchangeGrant (POST /api/v3/admin/exchanges/{id}/grants), when the grant's actor is not an actor of an endpoint application;
  • updateExchange (PATCH /api/v3/admin/exchanges/{id}), when a changed origin or destination would leave a live grant's actor outside both endpoints.

The actor id travels in detail. It is the actor your request named, or the actor of one of the Exchange's own grants, in your own tenant.

Common Causes

  • Adding a grant for the counterparty's integration actor to an OUTBOUND Exchange whose destination is external. The tenant's own sending application's actor is the one that encrypts.
  • Reusing an actor of a sibling application of the tenant that is not an endpoint of this Exchange.
  • Changing the origin of a DRAFT Exchange to another application while it still owns grants for the old one.

Response Example

{
  "type": "https://docs.ankatech.co/errors/exchange-grant-actor-not-participant",
  "title": "Exchange Grant Actor Not Participant",
  "status": 422,
  "detail": "Actor 8f14e45f-ceea-467a-9575-6c3a1f0b2d77 does not belong to an application that is an endpoint of this Exchange. A grant of the Exchange authorizes an actor of its origin or destination application only.",
  "instance": "/api/v3/admin/exchanges/7d2f4a10-9c31-4b8e-a5d6-2f11c0b47e93/grants",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Content-Type: application/problem+json, following RFC 9457 Problem Details.

How to Resolve

  1. Read the Exchange (getById) and note the applicationId of its origin and destination.
  2. Name an actor of one of those applications, or create one with createActor under the right application.
  3. If the relationship really involves another application, model it as its own Exchange with that application as an endpoint.
  4. When an endpoint change was refused, revoke the grants of the old endpoint's actors first (revokeExchangeGrant), then change the endpoint.

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