API Keys

Manage app API keys via API

App API keys are used to authenticate requests to your Spice runtime endpoints (SQL query, search, AI gateway, etc.). Each app has a primary and optional secondary API key for seamless rotation.

API Keys vs. Management API Tokens:

• API Keys - Authenticate requests to your Spice runtime (https://data.spiceai.io, https://flight.spiceai.io)

• Personal Access Tokens / OAuth Tokens - Authenticate requests to the Management API (https://api.spice.ai)

Get API Keys

GET https://api.spice.ai/v1/apps/{appId}/api-keys

Returns the API keys for a specific app.

Required scope: apps:read

Path Parameters

Parameter	Type	Description
appId	integer	The app ID

Response

200: OK

{
  "api_key": "abc123...",
  "api_key_2": "def456..."
}

Response Fields:

Field	Type	Description
api_key	string | null	Primary API key
api_key_2	string | null	Secondary API key (for rotation)

404: Not Found

Example

curl -H "Authorization: Bearer <token>" \
  https://api.spice.ai/v1/apps/123/api-keys

Regenerate API Key

POST https://api.spice.ai/v1/apps/{appId}/api-keys

Regenerates an API key for the specified app. This invalidates the previous key.

Required scope: apps:write

Path Parameters

Parameter	Type	Description
appId	integer	The app ID

Request Body

{
  "key_number": 1
}

Request Fields:

Field	Type	Default	Description
key_number	integer	1	Which key to regenerate: 0 (both), 1 (primary), or 2 (secondary)

Response

200: OK

{
  "api_key": "new_abc123...",
  "api_key_2": "def456...",
  "regenerated_key": 1
}

Response Fields:

Field	Type	Description
api_key	string | null	Primary API key
api_key_2	string | null	Secondary API key
regenerated_key	integer	Which key was regenerated (0, 1, or 2)

400: Bad Request

404: Not Found

Examples

Regenerate primary key (default):

curl -X POST https://api.spice.ai/v1/apps/123/api-keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Regenerate secondary key:

curl -X POST https://api.spice.ai/v1/apps/123/api-keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"key_number": 2}'

Regenerate both keys:

curl -X POST https://api.spice.ai/v1/apps/123/api-keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"key_number": 0}'

Python:

import requests

# Regenerate primary key
response = requests.post(
    f"https://api.spice.ai/v1/apps/{app_id}/api-keys",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    },
    json={"key_number": 1}
)

keys = response.json()
print(f"New primary key: {keys['api_key']}")

Node.js:

const response = await fetch(
  `https://api.spice.ai/v1/apps/${appId}/api-keys`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ key_number: 1 })
  }
);

const keys = await response.json();
console.log('New primary key:', keys.api_key);

Using API Keys

API keys are used to authenticate requests to your Spice runtime endpoints:

SQL Query API

curl -H "x-api-key: <your-api-key>" \
  https://data.spiceai.io/v1/sql \
  -d "SELECT * FROM my_dataset LIMIT 10"

Arrow Flight API

from spice import Client

client = Client("flight.spiceai.io", api_key="<your-api-key>")
result = client.query("SELECT * FROM my_dataset")

AI Gateway (OpenAI Compatible)

curl https://data.spiceai.io/v1/chat/completions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Search API

curl https://data.spiceai.io/v1/search \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "datasets": ["my_dataset"],
    "text": "search query"
  }'

Key Rotation Strategy

Use the dual API key system for zero-downtime key rotation:

Step-by-Step Rotation

1. Generate secondary key (if not already created)

   curl -X POST https://api.spice.ai/v1/apps/123/api-keys \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"key_number": 2}'

2. Update clients to use secondary key

   Deploy updated applications with api_key_2 over time. Both keys remain valid.

3. Verify all clients are using secondary key

   Monitor application logs and runtime metrics to ensure no clients are using the old key.

4. Regenerate primary key

   curl -X POST https://api.spice.ai/v1/apps/123/api-keys \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"key_number": 1}'

5. Swap keys (optional)

   Update clients back to primary key and regenerate secondary for next rotation.

Rotation Script

import requests
import time

def rotate_api_keys(app_id, token):
    """Zero-downtime API key rotation"""
    base_url = "https://api.spice.ai/v1"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }

    # Step 1: Get current keys
    response = requests.get(f"{base_url}/apps/{app_id}/api-keys", headers=headers)
    current_keys = response.json()
    print(f"Current primary key: {current_keys['api_key'][:10]}...")

    # Step 2: Generate new secondary key
    print("Generating new secondary key...")
    response = requests.post(
        f"{base_url}/apps/{app_id}/api-keys",
        headers=headers,
        json={"key_number": 2}
    )
    new_keys = response.json()
    new_secondary = new_keys['api_key_2']
    print(f"New secondary key: {new_secondary[:10]}...")

    # Step 3: Update your applications to use new_secondary
    print("Deploy applications with new secondary key...")
    print("Waiting for deployment to complete...")
    time.sleep(60)  # Wait for deployment

    # Step 4: Regenerate primary key (old primary is now retired)
    print("Regenerating primary key...")
    response = requests.post(
        f"{base_url}/apps/{app_id}/api-keys",
        headers=headers,
        json={"key_number": 1}
    )
    final_keys = response.json()
    print(f"New primary key: {final_keys['api_key'][:10]}...")

    print("Rotation complete!")
    print(f"Active keys: primary={final_keys['api_key'][:10]}..., secondary={final_keys['api_key_2'][:10]}...")

# Usage
rotate_api_keys(app_id=123, token="your-pat-token")

Security Best Practices

Key Management

1. Rotate Regularly - Rotate keys every 90 days or after suspected exposure

2. Use Secondary Key - Leverage the dual-key system for zero-downtime rotation

3. Never Commit - Don't commit API keys to version control

4. Environment Variables - Store keys in environment variables or secrets managers

5. Monitor Usage - Track API key usage in runtime logs and metrics

Storage

# ✅ Good: Environment variable
export SPICE_API_KEY="your-api-key"

# ✅ Good: Secrets manager (e.g., AWS Secrets Manager)
aws secretsmanager get-secret-value --secret-id spice-api-key

# ❌ Bad: Hardcoded in code
const apiKey = "abc123...";  // Never do this!

# ❌ Bad: Committed to git
# .env file committed to repository

Access Control

• Limit apps:write scope to prevent unauthorized key regeneration

• Use separate apps for development, staging, and production

• Audit API key regeneration events

Troubleshooting

401 Unauthorized

If you receive 401 Unauthorized when using an API key:

1. Verify the key - Ensure you're using the correct key from the response

2. Check the header - Use x-api-key header (or Authorization: Bearer for AI Gateway)

3. Test the key - Use the health endpoint to verify:

   curl -H "x-api-key: <your-api-key>" \
     https://data.spiceai.io/health

4. Regenerate if needed - The key may have been rotated

Key Not Working After Rotation

If clients fail after key rotation:

1. Check propagation - Keys are updated immediately but may take a few seconds to propagate

2. Verify client config - Ensure clients are using the correct key variable

3. Test both keys - Both primary and secondary keys should work

4. Check logs - Look for authentication errors in runtime logs

Monitoring

Track API key usage through:

• Portal Monitoring - View request counts by API key in the portal

• Runtime Logs - Check authentication events in runtime logs

• Metrics - Monitor request rates and error rates by key

Terraform

API keys are available as an attribute on the spiceai_app resource. See Terraform Provider for full documentation.

output "app_api_key" {
  value     = spiceai_app.example.api_key
  sensitive = true
}

See also:

• Apps API - Manage your apps

• Portal API Keys - View keys in the portal

• SQL Query API - Query your data

• AI Gateway - Use AI models