API Keys for Programmatic Access

AMD AI Workbench API keys authentication inference programmatic access

API Keys for Programmatic Access#

API keys provide secure programmatic access to your deployed AI models and other project resources 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#

Create a New Key#

  1. Click the Create API Key button

  2. Configure your API key:

    • Name: Provide a descriptive name (e.g., “Production Inference Key”)

    • Validity Period: Choose expiration time or select “Never expires”

    • Linked 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

  3. Click Create

Save Your API Key#

Important

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

  1. Copy the API key immediately after creation

  2. Store it securely in your application’s secrets management system

  3. Never commit API keys to version control or share them publicly

The key will appear in the format: amd_aim_api_key_hvs.CAESIJlWWvb3r...

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

Using API Keys#

Basic Authentication#

Include the API key in the Authorization header of your HTTP requests:

curl -X POST https://your-workbench-url/v1/inference \
  -H "Authorization: Bearer amd_aim_api_key_hvs.CAESIJlWWvb..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-2-7b-chat",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Python Example#

import requests

API_KEY = "amd_aim_api_key_hvs.CAESIJlWWvb..."
BASE_URL = "https://your-workbench-url"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "llama-2-7b-chat",
    "messages": [
        {"role": "user", "content": "What is machine learning?"}
    ]
}

response = requests.post(
    f"{BASE_URL}/v1/inference",
    headers=headers,
    json=payload
)

print(response.json())

JavaScript/TypeScript Example#

const API_KEY = "amd_aim_api_key_hvs.CAESIJlWWvb...";
const BASE_URL = "https://your-workbench-url";

async function runInference() {
  const response = await fetch(`${BASE_URL}/v1/inference`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'llama-2-7b-chat',
      messages: [
        { role: 'user', content: 'What is machine learning?' }
      ]
    })
  });

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

Managing API Keys#

Viewing API Keys#

The API Keys page displays all keys for your project:

  • Name: The descriptive name you provided

  • Key: Truncated version for identification (full key not shown)

  • Linked Deployments: Number of deployed models this key can access

  • Created: When the key was created

  • Expires: When the key will expire (if applicable)

Editing API Key Bindings#

To change which deployments a key can access:

  1. Click the Edit icon next to the API key

  2. Update the Linked Deployments selection

    • Add deployments to grant access

    • Remove deployments to revoke access

  3. Click Save

Note

Changing bindings immediately affects which endpoints the key can access.

Deleting an API Key#

To revoke an API key:

  1. Click the Delete icon next to the API key

  2. Confirm the deletion

Warning

Deletion immediately revokes the key. Any applications using this key will lose access immediately. 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: Add API keys to .gitignore or .env.local files

  • 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:

  1. Delete the key immediately from the API Keys page

  2. Create a new key with a different name

  3. Update applications with the new key

  4. 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#

TTL (Time to Live) Options#

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

  • Never expires (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 by Cluster Auth and enforced automatically.

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