Skip to main content

​
API Keys API

The apiKeys module allows your backend to act as an identity provider for other applications. Using this module, you can programmatically provision and manage API Keys that your users can then use to authenticate against your own public APIs. Note: These are keys you issue to your customers, not the key you use to authenticate the @wacht/backend SDK. 
import { WachtClient } from "@wacht/backend";

const client = new WachtClient({ apiKey: process.env.WACHT_API_KEY });

​
API Auth Apps

Before you can issue API Keys, you must define an API Auth App. An App defines the capabilities, rate limits, and contextual boundaries for the keys issued underneath it.

​
createApiAuthApp(request)

Create a new category of API keys. 
const app = await client.apiKeys.createApiAuthApp({
  name: "Acme public API V2",
  slug: "acme-v2",
  permissions: ["read:data", "write:data"],
  rate_limit_scheme_slug: "standard_tier",
  organization_id: "org_abc123" // Keys will be scoped to this org
});
​
request
CreateApiAuthAppRequest
required

​
listApiAuthApps()

List the active API configurations in your environment. 
const apps = await client.apiKeys.listApiAuthApps();
  • client.apiKeys.getApiAuthApp(appName)
  • client.apiKeys.updateApiAuthApp(appName, request)
  • client.apiKeys.deleteApiAuthApp(appName)

​
Provisioning Keys

API Keys are provisions underneath a specific App.

​
createApiKey(appName, request)

Generates a new secure API key. This is the only time the full secret key (wk_live_...) is returned. Record it carefully. 
const keyRecord = await client.apiKeys.createApiKey("acme-v2", {
  name: "Production Backend Key",
  owner_user_id: "usr_abc123" // The developer who owns this key
});

// Send this once to the user to store in their .env
console.log(keyRecord.secret);
​
appName
string
required
The parent API Auth App’s name or slug.
​
request
CreateApiKeyRequest
required

​
listApiKeys(appName)

Retrieve metadata about all keys provisioned under an app (but never the secrets themselves). 
const keys = await client.apiKeys.listApiKeys("acme-v2");
​
appName
string
required
The parent App slug whose keys you wish to list.

​
Rotating and Revoking

API Keys are critical security credentials. If a customer accidentally leaks a key, it must be neutralized.

​
revokeApiKey(request)

Instantly invalidates the key. Any requests made to your API (validated via gateway.verifyApiKeyRequest) using this key will immediately return HTTP 403. 
await client.apiKeys.revokeApiKey({
  api_key_id: "key_xyz789"
});
​
request
RevokeApiKeyRequest
required

​
rotateApiKey(request)

Generates a new secret for an existing key identity, instantly invalidating the old one. 
const rotated = await client.apiKeys.rotateApiKey({
  api_key_id: "key_xyz789"
});

// Provide the new secret to the developer
console.log(rotated.secret);
​
request
RotateApiKeyRequest
required