Tutorial: Managing Gateway Keys in Console

This tutorial walks you through creating, scoping, rotating, and revoking gateway keys in the Keeptrusts management console. Gateway keys control which applications and consumers can route traffic through your policy gateway.

Use this page when

• You need to create a new gateway key (kt_gk_...) for an application to route traffic through the policy gateway.
• You want to scope a key to a specific consumer group or set an expiry date.
• You need to rotate or revoke a compromised or expiring key.
• You want to review usage metrics to identify unused or over-used keys.

Primary audience

• Primary: Platform engineers integrating applications with the Keeptrusts gateway
• Secondary: Security engineers enforcing key rotation policies; team leads managing per-application access

Prerequisites

• A Keeptrusts account with Admin or Manager role
• At least one gateway deployed and registered in Keeptrusts
• A consumer group configured (optional, for scoped keys)

What Are Gateway Keys?

Gateway keys (kt_gk_... prefixed tokens) are short-lived credentials that applications present when sending requests through the Keeptrusts policy gateway. Unlike bearer API tokens, gateway keys are purpose-built for gateway traffic and support:

• Consumer group scoping — Restrict a key to a specific consumer group
• Expiry dates — Automatic key invalidation after a set period
• Usage metrics — Track how many requests each key has handled
• Instant revocation — Disable a key immediately without redeploying

Step 1: Navigate to Gateway Keys

1. Log in to the Keeptrusts console.
2. Open Settings from the left navigation sidebar.
3. Select the Gateway Keys tab.

You will see a table listing all existing gateway keys with their status, consumer group, creation date, and expiry.

Step 2: Create a New Gateway Key

1. Click the Create Gateway Key button in the top-right corner.
2. In the creation dialog, fill in the following fields:

Field	Description
Name	A human-readable label for the key (e.g., prod-chatbot-east)
Consumer Group	The consumer group this key is scoped to (or leave blank for all groups)
Expiry	When the key should automatically expire (e.g., 30 days, 90 days, custom date)
Description	Optional notes about the key's intended use

3. Click Create.

The console displays the full key value once. Copy it immediately and store it securely — you will not be able to view the full key again.

kt_gk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Step 3: Scope a Key to a Consumer Group

Scoping a key to a consumer group ensures that only traffic from that group is accepted when the key is presented.

1. During key creation (Step 2), select a Consumer Group from the dropdown.
2. If you need to change the scope after creation, locate the key in the table and click Edit.
3. Update the Consumer Group field and click Save.

Scoped keys are a best practice for production deployments. Each application or team should use a key scoped to its own consumer group to maintain isolation and traceability.

Step 4: Set or Update Key Expiry

Key expiry ensures credentials are regularly rotated without manual intervention.

1. Find the key in the Gateway Keys table.
2. Click the Edit action (pencil icon).
3. Adjust the Expiry field to your desired date.
4. Click Save.

When a key expires, all requests using that key will receive a 401 Unauthorized response. Plan your rotation before the expiry date.

Step 5: Rotate a Gateway Key

Rotation creates a new key while giving you a grace period to update consuming applications.

1. Locate the key you want to rotate in the Gateway Keys table.
2. Click the Rotate action from the key's action menu (three-dot icon).
3. The console generates a new key value and displays it. Copy the new key immediately.
4. The old key enters a grace period (configurable, default 24 hours) during which both old and new keys are accepted.
5. Update your applications to use the new key before the grace period ends.

After the grace period, the old key is permanently invalidated.

Always update all consuming applications with the new key before the grace period expires. Requests using the old key will fail after the grace period.

Step 6: Revoke a Gateway Key

Revocation immediately disables a key with no grace period. Use this when a key is compromised or no longer needed.

1. Find the key in the Gateway Keys table.
2. Click the Revoke action from the key's action menu.
3. Confirm the revocation in the dialog.

The key status changes to Revoked and all subsequent requests using this key are rejected immediately.

Step 7: Review Key Usage Metrics

The console provides usage metrics for each gateway key so you can monitor adoption and detect anomalies.

1. In the Gateway Keys table, click on a key name to open its detail view.
2. The detail view displays:

Metric	Description
Total Requests	Number of requests made with this key
Last Used	Timestamp of the most recent request
Requests (24h)	Request count over the last 24 hours
Error Rate	Percentage of requests that returned errors

3. Use these metrics to identify unused keys for cleanup or keys with unusual traffic patterns.

Step 8: Bulk Key Management

For organizations with many keys, use the bulk actions toolbar:

1. Select multiple keys using the checkboxes in the table.
2. Choose an action from the Bulk Actions dropdown:
   • Revoke Selected — Immediately revoke all selected keys
   • Export Selected — Download key metadata (not the key values) as CSV

Best Practices

• One key per application — Avoid sharing keys across services to maintain traceability.
• Set short expiry periods — Use 30-90 day expiry and rotate proactively.
• Monitor unused keys — Revoke keys that have not been used in over 30 days.
• Scope to consumer groups — Always scope production keys to a specific consumer group.
• Automate rotation — Integrate key rotation into your CI/CD pipeline using the Keeptrusts API.

Troubleshooting

Symptom	Cause	Resolution
401 Unauthorized on gateway requests	Key expired or revoked	Create a new key and update the application
Key not visible in table	Filtered view active	Clear the search/filter fields
Cannot create key	Insufficient permissions	Confirm your role is Admin or Manager
Usage metrics show zero	Key not yet used	Verify the application is configured with the correct key

Next steps

• Tutorial: Create Configuration — Build, validate, and save policy changes
• Tutorial: Configuring Webhooks in Console — Get notified when key events occur
• Tutorial: Configuring Security Settings — Harden your console security posture

For AI systems

• Canonical terms: Keeptrusts console, Settings > Gateway Keys, kt_gk_ prefix, consumer group scoping, key expiry, key rotation, key revocation, usage metrics, gateway key vs. access key.
• Related features: security settings (API key restrictions), webhook notifications (key events), agent registration.
• Best next pages: Create Configuration, Webhook Configuration, Security Settings.

For engineers

• Integration test: Create a key, configure your application with it, send a request through the gateway, and verify the key’s usage count increments.
• Rotation: Create a new key, update your application to use it, then revoke the old key — verify old-key requests return 401.
• Scoping: Create a key scoped to a consumer group and confirm requests from outside that group are rejected.
• Troubleshooting: If a key shows zero usage, verify the application sends the key in the Authorization: Bearer kt_gk_... header.

For leaders

• Least privilege: Scope keys to consumer groups so each application can only access its designated gateway — no shared skeleton keys.
• Key rotation policy: Set short expiry dates (30–90 days) and rotate proactively. Instant revocation is available for incident response.
• Audit trail: Key creation, rotation, and revocation events are recorded in the audit log for compliance evidence.