Create an Exchange Client Key

Use this guide to create an Exchange Client Key for a Broker backend. The backend uses this key during token exchange to act for a Subscriber or Broker Advisor. For the authentication methods, see Authentication.

Prerequisites

• A Broker Administrator who can sign in to Quarzo in the target environment.
• A Broker with an Exchange Client configured by Quarzo operations.
• A secrets manager or private storage that only the backend process can read.
• A Broker Service Account with an active Service Key for the machine token that delegation requires. See Get a Service Account and a Service Key.

1. Open the Delegation page

Ask the Broker Administrator to complete these steps in broker-front:

1. Open Administration → Delegation in the sidebar.
2. Find the Exchange Client section.
3. Select Copy beside Client id.
4. Select Copy beside Project id, below Client id.
5. Give both IDs to the backend operator for the same Broker and environment.

The Client ID is not a secret. If the page cannot load the Exchange Client, ask Quarzo operations to check the Broker configuration.

Delegation also needs the project ID of the Exchange Client, for the audience of the machine token. The Project id field shows this value. The project ID is not a secret. The machine token must request both this project and the Quarzo project as audiences. See Get a delegated token.

2. Generate and download the key

1. In the Exchange Client Keys section, select Generate a key.
2. Enter a Label that identifies the backend that will hold the key, for example Production API server.
3. Select Generate.
4. In the Your key is ready dialog, select Download before you close the dialog.
5. Give the file to the backend operator through a secure channel, for example a secrets manager.

The label must contain 1 to 100 characters. Do not send the key file by email or chat. Quarzo provides the private key only once and does not store it. If you close the dialog without the file, generate a new key. Revoke the unused key on the Delegation page.

The downloaded file has the name <label>-<keyId>.json. It contains these fields:

{
  "type": "application",
  "keyId": "<key-id>",
  "key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
  "appId": "<exchange-client-application-id>",
  "clientId": "<exchange-client-id>"
}

The key field contains the private key. The clientId field must match the Client ID from the Delegation page.

Expected result: the key appears in the list with status ACTIVE and an expiration date. The backend operator has the downloaded file and the matching Client ID.

3. Store and verify the key

1. Store the file in a secrets manager or a file that only the backend process can read.
2. Configure the backend with the key file from the same Broker and environment as its Service Account.
3. Follow Get a delegated token to verify token exchange and a Quarzo request.

Never commit the file. Never log the file, its private key, client assertions, or access tokens. Keep the file out of browser code and public assets.

The delegated-token example uses this environment variable:

export QUARZO_EXCHANGE_CLIENT_FILE='/private/path/to/exchange-client-key.json'

Expected result: the example displays GET /v1/authentication/me with delegated token: HTTP 200.

4. Rotate or revoke the key

Each Exchange Client Key expires 365 days after generation. Rotate the key before the expiration date on the Delegation page. More than one key can be active at the same time.

1. Generate and download a new key on the Delegation page.
2. Deploy the new file to every backend instance that uses the old key.
3. Obtain a delegated token with the new key.
4. Verify a Quarzo request with that token.
5. On the Delegation page, select Revoke for the old key.
6. Confirm the revocation in the dialog.
7. Remove the old private key from backend storage.

Expected result: the old key has status REVOKED. The backend uses the new key for token exchange.

If a key is lost or exposed, revoke it immediately. Generate a replacement key for the backend. Revocation cannot be undone. The revoked key cannot authenticate new token exchanges. A token issued before revocation stays valid until it expires, 15 minutes at most.