Skip to content

Grant or revoke a party's access to an exchange

Give one identity of an application at either end of an exchange the right to run chosen operations with chosen keys, or take that right away. Each grant is a capability grant owned by the exchange and placed in the exchange's context.

Who can do it

A person who holds both the permission to update exchanges and the permission to create capability grants (to add one) or to revoke them (to revoke one). The console shows Add grant and Revoke grant only to such a person. A tenant administrator and a tenant key manager hold both. A platform super administrator does it from inside the tenant, where the console acts as a tenant administrator.

Before you start

  • The exchange exists and has not ended. A grant is added to the saved exchange: a new exchange needs its endpoints and context first.
  • The identity is a cryptographic actor of the application at the origin or the destination. The editor offers only those actors.
  • The keys the grant names exist in the tenant. For a re-encryption or re-signing grant, each target key must be active.
  • A grant authorizes only while the exchange is active. Added to a draft, ready or suspended exchange, it is held until activation or resume. An active or suspended exchange keeps at least one live grant.
  • A grant that would add an operation permission to its actor needs a person who can assign actor roles.

Steps

  1. Open Cryptographic Exchanges and select the exchange's row. The exchange opens in the editor.
  2. Open the Grants step.
  3. To add a grant:
    1. Select Add grant.
    2. Choose the Cryptographic Actor.
    3. Choose What the grant authorizes: Operations on a key, then tick the Operations and choose the Key; or Re-encrypt or re-sign, then choose the Operation and one or more Key pairs (source → target), selecting Add pair for each further pair.
    4. Optionally choose a Constraint Policy (optional) to limit the grant.
    5. Select Add grant.
  4. To revoke a grant, select Revoke grant on its row, type the actor's name (or the grant identifier when the actor has no name) to confirm, give a Reason, and select Revoke grant.

What you see when it worked

The grant appears in the Grants step with its actor, operations, keys, Constraint Policy version and status Live. On an active exchange it authorizes at once; on any other exchange it waits for activation or resume.

A revoked grant shows the status Revoked: its actor loses the grant at once, and the exchange keeps its other grants. Revoking cannot be undone; a new grant starts from the current policy version with new counters.

If it fails

What you see Cause What to do
Choose the endpoints and the context first; grants are added to the saved exchange. The exchange has not been saved yet Complete Endpoints and Exchange Context first
Neither endpoint application has an actor yet. No actor belongs to an application at either end Create an actor for one of the endpoint applications
The actor does not belong to an application at either end of this exchange. The actor is not a participant Choose an actor of the origin or destination application
This grant would overlap a live grant of the same actor. Nothing was written. The actor already holds a live grant that overlaps this one; the conflicting grants are listed Change the new grant, or revoke the existing one first
This actor belongs to internal crypto use case <id> and acts only for it, so it cannot receive authority here. Choose an actor that no use case owns. An internal use case owns the actor Choose another actor
This is the exchange's last live grant. An active or suspended exchange keeps at least one: add another grant first, or revoke the exchange itself. Revoking would leave the exchange without a live grant Add another grant first, or revoke the exchange
Activating this exchange would add operation permissions to its actor, and your account cannot confer them. An administrator who can assign actor roles must activate it. The grant would add an operation permission to its actor, and you cannot assign actor roles Ask an administrator who can assign actor roles
Add grant and Revoke grant are not offered The exchange has ended, or you lack the grant permissions Clone an ended exchange; or ask a tenant administrator

Without the console

Surface How
Key management CLI ankasecure-km exchanges add-grant --id <uuid> --actor-id <uuid> --capability <capability> --asset-kid <kid> (or --pair <sourceKid:targetKid>, --constraint-policy-id <uuid>, --body-file); exchanges revoke-grant --id <uuid> --grant-id <uuid> --reason <text>
Admin SDK ExchangeOperations.createGrant(UUID, ExchangeGrantRequest), ExchangeOperations.revokeGrant(UUID, UUID, RevokeExchangeGrantRequest)
API POST /api/v3/admin/exchanges/{id}/grants (operation createExchangeGrant); POST /api/v3/admin/exchanges/{id}/grants/{grantId}/revoke (operation revokeExchangeGrant)