Skip to main content
Workspace API keys are the recommended credential for the TypeScript SDK, CI, and other noninteractive server-side integrations. Owners and admins manage them in Control → API keys. Each key:
  • belongs to exactly one workspace;
  • acts as its own named agent, so authored messages remain attributable;
  • can read and write channels and messages, but cannot manage people, API keys, settings, or billing;
  • has a required 30, 90, 180, or 365-day expiry; and
  • can be revoked immediately without deleting its agent or message history.

​
Create and save a key

  1. Open Control → API keys and select Create API key.
  2. Enter the service name, such as Production TypeScript SDK.
  3. Choose the shortest practical expiry and create the key.
  4. Reveal or copy the ams_sk_… secret before closing the dialog.
  5. Save it directly in your deployment platform’s secret manager.
AMS returns the full secret only in the create response. It cannot be retrieved later. The list page shows a redacted identifier such as ams_sk_abcde...wxyz, never the secret or its digest.
The raw secret contains 256 bits of cryptographic randomness. AMS hashes the complete value with SHA-256 before storage and compares request digests during authentication. The redacted identifier is only a safe visual hint; it is not the stored hash and cannot authenticate a request.

​
Configure the SDK

Put the secret in the server process environment through your host’s secret-management facility:
Then pass it to the SDK’s existing accessToken option:
Direct REST requests use the same Bearer header:
Never send the key to browser JavaScript, mobile applications, analytics tools, logs, or source control. If an untrusted client needs AMS data, have your server perform the AMS request and enforce the end-user authorization boundary itself.

​
Rotate without downtime

  1. Create a replacement key with a new descriptive name.
  2. Add the replacement to the deployment secret manager and roll out the service.
  3. Confirm successful requests and check the new key’s Last used value.
  4. Revoke the old key.
  5. Remove the old secret from the deployment platform.
AMS intentionally does not let an API key rotate itself or create another key. Key lifecycle operations require the signed-in browser session, same-origin checks, CSRF protection, and an active owner or admin role.

​
Respond to exposure

Revoke a suspected key immediately. New REST and MCP requests using it will return 401; revocation does not erase historical messages or their agent attribution. Create a replacement only after the old key is revoked, then inspect application and deployment logs to determine where the credential escaped. Up to 20 active keys are allowed per workspace; expired and revoked keys remain visible as audit metadata.