createApiKey()

Creates a key for one API auth app and returns the one-time secret. The backend binds the created key to the app slug from the URL, not from the request body.

Usage

The following example shows a basic usage of the backend client from @wacht/nextjs/server.

import { wachtClient } from '@wacht/nextjs/server';export async function issueApiKey() {  const client = await wachtClient();  return client.apiKeys.createApiKey('internal-api', {    name: 'Primary production key',    permissions: ['users:read', 'users:write'],    metadata: { owner: 'backend-service' },  });}

Signature

function createApiKey(  appName: string,  request: CreateApiKeyRequest,): Promise<ApiKeyWithSecret>

CreateApiKeyRequest

›

appName?: string | undefined;

Slug of the API auth app that should own the key.

›

name?: string | undefined;

Human-readable key name used in audit and admin views.

›

permissions?: string[] | undefined;

Optional permission list attached to this key.

›

metadata?: Record<string, unknown> | undefined;

Optional metadata object stored with the key record.

›

owner?: string | undefined;

Owning service or team identifier.

›

environment?: string | undefined;

Environment tag (for example `production`).

›

expires_at?: string | undefined;

Optional expiration timestamp (ISO-8601 string).

Return value

›

key?: ApiKey | undefined;

Persisted API key record metadata.

›

id?: string | undefined;

Stable key id.

›

app_slug?: string | undefined;

Owning app slug.

›

name?: string | undefined;

Key display name.

›

key_prefix?: string | undefined;

Public key prefix.

›

key_suffix?: string | undefined;

Public key suffix.

›

permissions?: string[] | undefined;

Permissions attached to the key.

›

secret?: string | undefined;

Newly issued secret value. This is only returned once.

What the backend enforces

The backend resolves the target app by appName and creates the key inside that app boundary.

Only fields supported by CreateApiKeyRequest are accepted for this call. Membership scope fields are not part of this endpoint contract.

Examples

Issue an expiring key for one app

import { wachtClient } from '@wacht/nextjs/server';export async function issueTemporaryKey() {  const client = await wachtClient();  return client.apiKeys.createApiKey('internal-api', {    name: 'temporary-import-key',    permissions: ['users:read'],    expires_at: '2026-12-31T23:59:59Z',  });}