Create / Rotate / Revoke Client

Creating, Rotating, and Revoking Integration Clients

Integration clients and their API keys are managed through the TenantIntegrationClients dashboard surface. An authorized tenant administrator or an authorized platform user operating in a valid selected-tenant context can use this surface. Each client represents one external system or integration and carries its own API key and scope set.

Creating a New Integration Client

1. Sign in to the dashboard using an authorized tenant or platform account.
2. Open the integration-client management surface (TenantIntegrationClients). The tenant path requires tenant-admin status and membership in the tenant-admin group. The selected-tenant platform path requires a valid selected tenant and Manage tenant integrations permission.
3. Click Add New Client.
4. Fill in the fields:
   • Client Name — a descriptive label identifying the external system (for example, "BI Dashboard" or "Nightly ETL Job").
   • Description — optional context for administrators.
   • Scopes — select from ReportsRead, UsageRead, and RawResponsesRead. The plan must enable Report API access for ReportsRead or UsageRead, and Raw response API access for RawResponsesRead.
   • Expires At — required, in the future, and no later than the configured maximum; a shorter maximum applies when RawResponsesRead is present.
5. Click Create. The system generates a new API key and displays it once at this point.
6. Copy the key immediately and store it in a secrets manager. The full key value is not retrievable after this screen is closed.

The key is hashed before storage. Survanta cannot recover a lost key. If the key is lost, rotate it immediately.

Rotating an API Key

Key rotation replaces the current API key with a new one while preserving the client record and its assigned scopes. Rotate a key whenever it may have been compromised or as part of a scheduled security rotation policy.

1. In the integration-client list, locate the client by name.
2. Click Rotate Key on the client's action menu.
3. Confirm the rotation. The old key is invalidated immediately.
4. Copy and store the new key from the no-cache one-time secret view, then update the consuming system. Rotation also sets a fresh maximum permitted expiry, activates the client, and clears revocation.

There is no grace period — the old key stops working the moment rotation is confirmed. Coordinate with the integration consumer before rotating in production.

Revoking a Client

Revoking a client disables the client and invalidates its key while retaining the record for audit. Use this when an integration is decommissioned.

1. In Settings → Integration Clients, locate the client.
2. Click Revoke. The current controller exposes revocation, not hard deletion.
3. Confirm the revocation. Any subsequent request using the old key receives 401 Unauthorized with errorMessage set to Authentication is required. Provide valid credentials or a valid API key.

Viewing Existing Clients

The integration clients list shows:

Each generated key is displayed once, after creation or rotation, and cannot be retrieved afterward.

Scope Assignment Rules

• A client may hold any combination of ReportsRead, UsageRead, and RawResponsesRead.
• Scopes are never placed inside user permission groups.
• The application service supports validated metadata/scope updates, but the current tenant controller exposes list, create, rotate, revoke, and audit actions only; do not document an Edit action that is not routed.
• Plan downgrades can revoke newer excess active clients deterministically, and expired clients do not consume quota capacity.