Managing API Keys & Gateway Keys

Keeptrusts uses two token types for different purposes: access keys for control-plane API access and gateway keys for AI traffic through the gateway. Both are managed through the same token system but serve distinct roles. This guide covers creation, scoping, rotation, and revocation.

Use this page when

• You need to create, scope, rotate, or revoke API access keys or gateway keys.
• You want to understand the difference between access keys (kt_ak_...) and gateway keys (kt_gk_...).
• You are setting up key lifecycle automation (rotation schedules, expiry, revocation).
• You need to scope gateway keys to specific models or policies for least-privilege access.

Primary audience

• Primary: Developers managing API credentials for their applications, Platform Administrators governing token lifecycle
• Secondary: Security Engineers auditing key usage, DevOps Engineers integrating keys into CI/CD pipelines

Token Types

Type	Prefix	Purpose	Where Used
Access Key	kt_ak_...	Control-plane API calls (events, config, admin)	Server-side automation, CI/CD
Gateway Key	kt_gk_...	AI traffic through the gateway	Applications, Chat Workbench

Both types are standard API tokens stored in the tokens table with a token_type field. The console Settings pages provide filtered views for each type.

Creating Access Keys

Via the Console

1. Navigate to Settings → Access Keys.
2. Click Create Access Key.
3. Fill in the details:
   • Name: Descriptive label (e.g., ci-pipeline-prod)
   • Expiry: Choose a TTL or set no expiry for service accounts
4. Copy the key immediately — it is shown only once.

Via the CLI

kt tokens create \
  --type access \
  --name "ci-pipeline-prod" \
  --expires-in 90d

Output:

Access key created:
  Key:     kt_ak_prod_a1b2c3d4...
  Name:    ci-pipeline-prod
  Expires: 2026-07-22T00:00:00Z

Via the API

curl -X POST https://api.keeptrusts.com/v1/tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-pipeline-prod",
    "token_type": "access",
    "expires_at": "2026-07-22T00:00:00Z"
  }'

Creating Gateway Keys

Via the Console

1. Navigate to Settings → Gateway Keys.
2. Click Create Gateway Key.
3. Configure:
   • Name: app-production
   • Scope: Select allowed models and providers
   • Expiry: Recommended 30-90 days for production
4. Copy the generated kt_gk_... key.

Via the CLI

kt tokens create \
  --type gateway \
  --name "app-production" \
  --expires-in 30d

Scoping Gateway Keys

Gateway keys can be scoped to restrict which models and providers the key can access:

kt tokens create \
  --type gateway \
  --name "frontend-only" \
  --allowed-models "gpt-4o,gpt-4o-mini" \
  --expires-in 7d

This key can only route requests to gpt-4o and gpt-4o-mini. Requests to other models return 403 Forbidden.

Scope Examples

Use Case	Scope
Production app (cost control)	--allowed-models "gpt-4o-mini"
Internal tools (broad access)	No model restriction
Dev prototyping (time-limited)	--expires-in 24h
Partner integration (restricted)	--allowed-models "gpt-4o" --expires-in 90d

Key Rotation

Manual Rotation

The safest rotation approach for production keys:

# 1. Create the new key
kt tokens create \
  --type gateway \
  --name "app-production-v2" \
  --expires-in 30d

# 2. Deploy the new key to your application

# 3. Verify traffic flows through the new key
kt events tail --filter "token_name=app-production-v2" --limit 5

# 4. Revoke the old key
kt tokens revoke --name "app-production"

Overlap Window

Always maintain an overlap period where both old and new keys are valid:

Day 0:  Create new key, deploy to staging
Day 1:  Deploy new key to production
Day 3:  Verify all traffic uses new key
Day 5:  Revoke old key

Automated Rotation Script

#!/usr/bin/env bash
set -euo pipefail

KEY_NAME="app-production"
ROTATION_SUFFIX=$(date +%Y%m%d)
NEW_NAME="${KEY_NAME}-${ROTATION_SUFFIX}"

# Create new key
NEW_KEY=$(kt tokens create \
  --type gateway \
  --name "$NEW_NAME" \
  --expires-in 30d \
  --output json | jq -r '.key')

# Store in your secrets manager
echo "New key: $NEW_NAME"
echo "Deploy this key and then revoke the previous one."

Listing and Inspecting Keys

List All Tokens

kt tokens list

NAME                    TYPE      CREATED              EXPIRES              STATUS
ci-pipeline-prod        access    2026-04-01T10:00:00  2026-07-01T10:00:00  active
app-production          gateway   2026-04-15T14:00:00  2026-05-15T14:00:00  active
dev-prototyping         gateway   2026-04-23T09:00:00  2026-04-24T09:00:00  expired

Filter by Type

kt tokens list --type gateway

Inspect a Specific Token

kt tokens inspect --name "app-production"

{
  "name": "app-production",
  "token_type": "gateway",
  "created_at": "2026-04-15T14:00:00Z",
  "expires_at": "2026-05-15T14:00:00Z",
  "last_used_at": "2026-04-23T12:45:00Z",
  "status": "active",
  "allowed_models": ["gpt-4o", "gpt-4o-mini"]
}

Revoking Keys

Single Key

kt tokens revoke --name "dev-prototyping"

Via the Console

1. Go to Settings → Access Keys or Settings → Gateway Keys.
2. Find the key and click Revoke.
3. Confirm the revocation.

Revoked keys are immediately invalid. Any in-flight requests using the key will complete, but new requests are rejected with 401 Unauthorized.

Security Best Practices

Practice	Why
Use gateway keys for apps, access keys for automation	Separation of concerns
Set expiry on all keys	Limits damage from leaked keys
Scope gateway keys to needed models	Prevents cost surprises
Rotate keys every 30-90 days	Reduces exposure window
Never commit keys to version control	Use environment variables or secret managers
Monitor last_used_at for unused keys	Revoke stale keys promptly
Use unique names with dates for rotation	Makes audit trails clear

Next steps

• Chat Workbench for AI Prototyping — use gateway keys in the chat playground
• Local Development Setup — configure keys in your local environment
• Debugging AI Requests with Events — trace requests by token name

For AI systems

• Canonical terms: access key (kt_ak_...), gateway key (kt_gk_...), token type, rotation, revocation, expiry, scoping, POST /v1/tokens, kt tokens create.
• Access keys: control-plane API calls (events, config, admin). Gateway keys: AI traffic through the gateway.
• Console pages: Settings → Access Keys, Settings → Gateway Keys. Both are filtered views over the shared tokens table.
• Best next pages: Chat Workbench for Prototyping, Local Development Setup, Debugging with Events.

For engineers

• Create keys via console (Settings → Access Keys / Gateway Keys), CLI (kt tokens create --type access|gateway), or API (POST /v1/tokens).
• Copy keys immediately after creation — they are shown only once.
• Scope gateway keys to specific models to prevent cost surprises from unintended model access.
• Set expiry on all keys (30-90 day rotation recommended). Monitor last_used_at and revoke stale keys.
• Never commit keys to version control — use environment variables or secret managers.
• Revoked keys are immediately invalid; in-flight requests complete but new requests get 401.

For leaders

• Access keys and gateway keys provide separation of concerns: admin operations vs. AI traffic.
• Key rotation every 30-90 days limits the blast radius of leaked credentials.
• Scoped gateway keys enforce least-privilege for each application — only the models it needs.
• All key operations are auditable; last_used_at tracking identifies unused keys for cleanup.
• Key management is a security baseline requirement for SOC 2, ISO 27001, and similar compliance frameworks.