Skip to content

Design, validate and activate an exchange

Build a cryptographic exchange: who sends and who receives, the context it operates in, and the grants that say which identities may do what, with which keys. Then validate it and activate every grant at once.

Who can do it

A tenant administrator, a tenant key manager, or a platform super administrator from inside the tenant, where the console acts as a tenant administrator. The console offers New exchange only to a person who holds the permission to create exchanges; saving the draft, validating, activating and discarding each need their own permission on exchanges.

Adding grants to the exchange also needs the permission to create capability grants. Activation adds operation permissions to each grant's actor, so the person activating must also be able to assign actor roles.

The screen is for STANDARD tenants: a SIMPLE tenant does not see it, and on a RAPIDAPI tenant the platform creates the exchanges.

Before you start

  • At least one end of the exchange is one of your applications. The other end is another of your applications or an external counterparty, which you can classify with a counterparty type.
  • An exchange context exists for the exchange, or you create one from the editor.
  • The application at either end has a cryptographic actor, and the keys the grants will name exist. A grant can only be given to an actor of an application at one of the two ends.

Steps

  1. Open Cryptographic Exchanges and select New exchange. The editor walks through five steps; Save keeps your work and Save and Continue → moves to the next step.
  2. Overview: enter the Name (required) and a Business purpose. Optionally set the validity window, whose fields name the time zone they are read in.
  3. Endpoints: for the Origin and the Destination, choose One of your applications and select it, or External counterparty and enter the counterparty's name and type. The console shows the resulting Relationship: inbound, internal, outbound or same application.
  4. Exchange Context: select the context. Select New Exchange Context to create one without leaving the editor. The draft is saved for the first time once both endpoints and a context are chosen.

  5. Grants: select Add grant, choose the Cryptographic Actor, choose What the grant authorizes, then:

    • for Operations on a key, tick the Operations and choose the Key;
    • for Re-encrypt or re-sign, choose the Operation and one or more Key pairs (source → target).

    Optionally choose a Constraint Policy (optional), then select Add grant. Repeat for every identity that needs authority.

  6. Review and activate: read the summary, then select Validate (DRAFT to READY). Any violation is listed with its field.

  7. When validation passes, select Activate (every live grant, in one write). The confirmation, Activate this exchange?, lists what activation will do to each grant: its operations, its keys, its Constraint Policy and the operation permissions its actor gains. Select Activate.

An exchange can be changed only while it is a draft or ready. To change an active, suspended or ended exchange, select Clone: the copy opens as a new draft. To abandon a draft or ready exchange, select Discard Draft, then Discard.

What you see when it worked

The editor shows Validation passed — this exchange is READY. after validation, and after activation Exchange is ACTIVE with <n> grants. The status beside the exchange's name reads Active, and the review lists, for each grant, whether its identity can call the exchange. Each step of the editor carries a ✓ when it is complete.

The exchange appears in Cryptographic Exchanges and on the exchange topology. Its activity, in the side column, records each change.

If it fails

What you see Cause What to do
Choose both endpoints and a context to save this draft. A new draft is saved only once both endpoints and a context are chosen Complete Endpoints and Exchange Context
At least one end must be one of your applications. Both ends are external counterparties Make one end one of your applications
This exchange is <status>, so it can no longer be edited — only DRAFT or READY exchanges can. Clone it to edit a copy. The exchange is active, suspended or ended Select Clone to edit and change the copy
This exchange owns no live grant, so activating it would authorize nothing. Add a grant first. The exchange has no live grant Add a grant, validate again, then activate
The exchange context is <status>, not active, so it accepts no new grant or activation. The context is suspended or closed Reactivate the context, or move the draft to another context
The actor this exchange would authorize is <status>, not ACTIVE, so nothing can be conferred on it. Reactivate the actor before activating. A grant's actor is not active Reactivate the actor
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. You cannot confer the permissions the grants need Ask an administrator who can assign actor roles to activate it
Someone else changed this exchange while this page was open, so nothing was applied. Review its current state and try again. Another administrator changed the exchange Review the current state and repeat the action. See Concurrent Modification

Without the console

Surface How
Key management CLI ankasecure-km exchanges create --body-file <file>; exchanges update --id <uuid> --body-file <file>; exchanges validate --id <uuid>; exchanges preview-activation --id <uuid>; exchanges activate --id <uuid>; exchanges clone --id <uuid>; exchanges discard-draft --id <uuid> --expected-version <n>
Admin SDK ExchangeOperations.create(ExchangeCreateRequest), update(UUID, ExchangeUpdateRequest), validate(UUID), previewActivation(UUID), activate(UUID, ActivateRequest), cloneExchange(UUID, CloneRequest), discardDraft(UUID, int)
API POST /api/v3/admin/exchanges (operation createExchange); PATCH /api/v3/admin/exchanges/{id} (operation updateExchange); POST /api/v3/admin/exchanges/{id}/validate (operation validateExchange); GET /api/v3/admin/exchanges/{id}/activation-preview (operation previewExchangeActivation); POST /api/v3/admin/exchanges/{id}/activate (operation activateExchange); POST /api/v3/admin/exchanges/{id}/clone (operation cloneExchange); DELETE /api/v3/admin/exchanges/{id} (operation discardDraft)

Grants are added through a separate operation; see Grant or revoke a party's access to an exchange.