API Keys for Programmatic Access

AMD AI Workbench API keys authentication inference programmatic access

API Keys for Programmatic Access#

Note

API keys authenticate calls to inference endpoints on deployed models. To call the AI Workbench management API (projects, workloads, secrets, datasets, and related resources), use Keycloak/OAuth2 instead — see Authenticating to the AI Workbench API with Keycloak.

API keys provide secure programmatic access to your deployed AI models in AMD AI Workbench. Use API keys to integrate deployed models into your applications, automate workflows, or access inference endpoints from external systems.

What Are API Keys?#

API keys are cryptographic credentials that authenticate your applications when accessing deployed models. Each key:

Belongs to a project: Keys are scoped to specific projects and require project membership
Can be scoped to deployments: Optionally bind keys to specific deployed models for fine-grained access control
Has configurable lifetime: Set expiration times or create keys that never expire
Supports renewal: Renewable keys can be extended before expiration
Provides usage tracking: Optionally limit the number of uses

When to Use API Keys#

Use API keys when you need to:

Integrate deployed models into applications: Call inference endpoints from your backend services
Automate inference workflows: Run batch predictions or scheduled inference jobs
Access models from external systems: Connect from systems outside AMD AI Workbench
Implement fine-grained access control: Create different keys for different deployments or use cases
Share access without sharing accounts: Provide API access without sharing user credentials

Creating an API Key#

Navigate to API Keys#

Log in to AMD AI Workbench.
Navigate to your project.
Click on Settings in the project menu.
Select API Keys from the settings sidebar.

Create a New Key#

Click the Create API Key button.
Configure your API key:
- Name: Provide a descriptive name (e.g., “Production Inference Key”)
- Validity period: Choose an expiration time or select “Unlimited”
- Model deployments (optional): Select which deployed models this key can access
  - Leave empty to allow access to all project resources.
  - Select specific deployments to restrict access
Click Create.

Save Your API Key#

Important

The full API key is displayed only once and cannot be retrieved later.

Copy the API key immediately after creation.
Store it securely in your application’s secrets management system.
Never commit API keys to version control or share them publicly.

The key will appear in the format amd_aim_api_key_hvs.CAESIJlWWvb....

After closing the dialog, only a truncated version will be shown (e.g., amd_aim_api_key_••••••••1234) for security purposes.

Using API Keys#

Routing Modes#

There are two ways to route requests to a deployed model:

Precise routing (recommended) — set the x-ai-eg-backend (deployment UUID) and x-ai-eg-model (model name) request headers. This routes to the exact deployment regardless of model name, which is important when the same model is deployed in multiple projects.

Model-name fallback — omit the routing headers and include only model in the body. The gateway routes to any deployment serving that model name. Non-deterministic if multiple projects deploy the same model.

Precise Routing via Deployment UUID#

Find your deployment UUID in the AMD AI Workbench UI under the deployment details, or from the AIWB API URL (/v1/projects/{project}/inference/{uuid}).

curl#

curl -X POST https://<your-workbench-url>/v1/chat/completions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -H "x-ai-eg-backend: <deployment-uuid>" \
  -H "x-ai-eg-model: <your-model-name>" \
  -d '{
    "model": "<your-model-name>",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 512
  }'

Python#

import requests

API_KEY = "<your-api-key>"
BASE_URL = "https://<your-workbench-url>"
MODEL = "<your-model-name>"
DEPLOYMENT_UUID = "<deployment-uuid>"

response = requests.post(
    f"{BASE_URL}/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
        "x-ai-eg-backend": DEPLOYMENT_UUID,
        "x-ai-eg-model": MODEL,
    },
    json={
        "model": MODEL,
        "messages": [{"role": "user", "content": "What is machine learning?"}],
        "stream": False,
    },
)

result = response.json()
print(result["choices"][0]["message"]["content"])

JavaScript/TypeScript#

const API_KEY = "<your-api-key>";
const BASE_URL = "https://<your-workbench-url>";
const MODEL = "<your-model-name>";
const DEPLOYMENT_UUID = "<deployment-uuid>";

async function runInference() {
  const response = await fetch(`${BASE_URL}/v1/chat/completions`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      "x-ai-eg-backend": DEPLOYMENT_UUID,
      "x-ai-eg-model": MODEL,
    },
    body: JSON.stringify({
      model: MODEL,
      messages: [{ role: "user", content: "What is machine learning?" }],
      max_tokens: 512,
    }),
  });

  const result = await response.json();
  console.log(result);
}

Model-Name Fallback#

For standard OpenAI-compatible clients that cannot set custom headers — send only the model in the body. The gateway routes by model name, which is non-deterministic when the same model is deployed in multiple projects:

curl#

curl -X POST https://<your-workbench-url>/v1/chat/completions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<your-model-name>",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 512
  }'

Managing API Keys#

Viewing API Keys#

The API Keys page displays all keys for your project:

Name: The descriptive name you provided
Secret key: Truncated version for identification (full key not shown)
Created at: When the key was created
Created by: The user who created the key

Editing API Key Bindings#

To change which deployments a key can access:

Click the Edit link in the API key’s action menu.
Update the Model deployments selection.
- Add deployments to grant access.
- Remove deployments to revoke access.
Click Save.

Note

Changing bindings immediately affects which endpoints the key can access.

Deleting an API Key#

To revoke an API key:

Click the Delete icon next to the API key.
Confirm the deletion.

Warning

Deletion revokes the key immediately. Applications using this key will lose access. This action cannot be undone.

API Key Security Best Practices#

Protect Your Keys#

Store securely: Use environment variables or secrets management systems (e.g., AWS Secrets Manager, HashiCorp Vault).
Never commit to version control: Keep keys in ignored files (for example, .env.local) and ensure those files are listed in .gitignore.
Rotate regularly: Create new keys and delete old ones periodically.
Use scoped keys: Bind keys to specific deployments rather than granting full project access.

Monitor Usage#

Track key usage: Regularly review which keys are being used.
Set expiration: Create keys with limited lifetimes for temporary access.
Delete unused keys: Remove keys that are no longer needed.

Incident Response#

If an API key is compromised:

Delete the key immediately from the API Keys page.
Create a new key with a different name.
Update applications with the new key.
Review access logs to understand potential unauthorized access.

Troubleshooting#

Authentication Errors#

Error: 401 Unauthorized

Solutions:

Verify the API key is correct and complete.
Check that the key hasn’t expired.
Ensure the Authorization header format is correct: Bearer <key>.
Confirm the key hasn’t been deleted.

Access Denied Errors#

Error: 403 Forbidden

Solutions:

Verify the key is bound to the deployment you’re trying to access.
Check that the deployment is still running.
Confirm you’re accessing the correct endpoint URL.
Ensure your project membership is still active.

Key Not Found#

Error: API key not visible in the list

Solutions:

Verify you’re in the correct project.
Check that you have permission to view API keys.
Confirm the key wasn’t deleted by another team member.

Advanced Configuration#

Note

Advanced configuration is currently available only via the API.

TTL (Time to Live) Options#

When creating an API key, you can configure various validity options:

Unlimited (ttl: "0"): Key remains valid indefinitely
Hours (ttl: "24h"): Key expires after 24 hours
Days (ttl: "30d"): Key expires after 30 days
Custom durations: Use formats like “1h”, “7d”, “168h”

Usage Limits#

Optionally set a maximum number of uses for an API key:

Unlimited (num_uses: 0): No usage limit (default)
Limited uses (num_uses: 100): Key expires after 100 uses

Usage limits are tracked and enforced by Cluster Auth (the Workbench authentication service).

Explicit Max TTL#

For keys that should never exceed a certain lifetime:

Set explicit_max_ttl during creation
Renewal cannot extend beyond this limit
Useful for compliance requirements

Monitoring API Key Usage#

AMD AI Workbench provides a usage dashboard for each API key, showing request and token metrics over time. Use it to understand consumption patterns, detect anomalies, and audit activity across deployments.

Note

Metrics are only collected for requests made through the /v1/chat/completions endpoint.

Accessing the Dashboard#

Navigate to API Keys in your project menu.
Click the three-dot menu on the API key row.
Select View Details to open the key’s details page, which includes the metrics dashboard.

What the Dashboard Shows#

Summary statistics (top of the page):

Metric	Description
Total requests	All requests made with this key in the selected period
Successful requests	Requests that received a successful response
Failed requests	Requests that resulted in an error
Total tokens	Combined input and output tokens consumed
Linked deployments	Number of AIM deployments this key is bound to

Time-series charts (below the summary):

Requests over time — total, successful, and failed request counts broken down by time bucket
Token usage over time — total, input (prompt), and output (completion) tokens per time bucket

Filtering by Deployment#

Use the deployment filter to scope all metrics to a single AIM service. When a specific deployment is selected, the summary statistics and charts update to show only traffic routed to that deployment. This is useful for understanding per-model usage when a key has access to multiple deployments.

Time Range#

Use the time period selector to choose between preset ranges (for example, last hour, last day, last week). The Refresh button advances the time window to the current moment so you see the latest activity without reloading the page.

API Keys for Programmatic Access

Contents

API Keys for Programmatic Access#

What Are API Keys?#

When to Use API Keys#

Creating an API Key#

Navigate to API Keys#

Create a New Key#

Save Your API Key#

Using API Keys#

Routing Modes#

Precise Routing via Deployment UUID#

curl#

Python#

JavaScript/TypeScript#

Model-Name Fallback#

curl#

Managing API Keys#

Viewing API Keys#

Editing API Key Bindings#

Deleting an API Key#

API Key Security Best Practices#

Protect Your Keys#

Monitor Usage#

Incident Response#

Troubleshooting#

Authentication Errors#

Access Denied Errors#

Key Not Found#

Advanced Configuration#

TTL (Time to Live) Options#

Usage Limits#

Explicit Max TTL#

Monitoring API Key Usage#

Accessing the Dashboard#

What the Dashboard Shows#

Filtering by Deployment#

Time Range#

Related Resources#