Authentication

The Orka API uses API keys to authenticate requests. This page covers how to create, use, and manage your API keys.

API Keys

API keys are used to authenticate all requests to the Orka API. Each key is associated with a workspace and has specific permissions.

Creating an API Key

1. Log in to your Orka dashboard
2. Go to Settings → API Keys
3. Click Create New Key
4. Give your key a descriptive name (e.g., "Production Server", "Development")
5. Select the appropriate permissions
6. Click Create

Using Your API Key

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

1Authorization: Bearer sk_your_api_key_here

Example with cURL

1curl https://api.orka.ai/v1/agents \
2  -H "Authorization: Bearer sk_your_api_key_here"

Example with JavaScript

1const response = await fetch('https://api.orka.ai/v1/agents', {
2  headers: {
3    'Authorization': `Bearer ${process.env.ORKA_API_KEY}`,
4    'Content-Type': 'application/json',
5  },
6});

Example with Python

1import requests
2import os
3
4response = requests.get(
5    'https://api.orka.ai/v1/agents',
6    headers={
7        'Authorization': f'Bearer {os.environ["ORKA_API_KEY"]}'
8    }
9)

Key Types

| Type | Prefix | Description | |------|--------|-------------| | Secret Key | sk_ | Full API access, use on servers only | | Publishable Key | pk_ | Limited access, safe for client-side (read-only) |

Key Permissions

When creating an API key, you can restrict its permissions:

| Permission | Description | |------------|-------------| | agents:read | List and view agents | | agents:write | Create, update, and delete agents | | datastores:read | List and view datastores | | datastores:write | Create, update, and delete datastores | | documents:read | List and view documents | | documents:write | Upload and delete documents | | chat:query | Send chat queries |

Example: Read-Only Key

For applications that only need to query agents, create a key with only:

• agents:read
• datastores:read
• chat:query

Managing Keys

Listing Keys

View all your API keys in the dashboard under Settings → API Keys. For security, only the first and last 4 characters of each key are shown.

Revoking Keys

To revoke a key:

1. Go to Settings → API Keys
2. Find the key you want to revoke
3. Click the Delete button
4. Confirm the deletion

Rotating Keys

To rotate a key:

1. Create a new API key
2. Update your applications to use the new key
3. Verify the new key works correctly
4. Delete the old key

Best Practices

Environment Variables

Store API keys in environment variables:

1# .env file (never commit this!)
2ORKA_API_KEY=sk_your_api_key_here

Load in your application:

1// Node.js
2const apiKey = process.env.ORKA_API_KEY;

1# Python
2import os
3api_key = os.environ.get("ORKA_API_KEY")

Key Naming

Use descriptive names for your keys:

• Good: Production Server, CI/CD Pipeline, Local Development
• Bad: Key 1, test, asdf

Least Privilege

Create keys with only the permissions they need. A read-only dashboard doesn't need write permissions.

Regular Rotation

Rotate your API keys periodically (e.g., every 90 days) and immediately if you suspect a key has been compromised.

Error Responses

Invalid API Key

1{
2  "error": {
3    "code": "authentication_error",
4    "message": "Invalid API key provided."
5  }
6}

Status Code: 401 Unauthorized

Missing API Key

1{
2  "error": {
3    "code": "authentication_error",
4    "message": "No API key provided. Include your API key in the Authorization header."
5  }
6}

Status Code: 401 Unauthorized

Insufficient Permissions

1{
2  "error": {
3    "code": "permission_denied",
4    "message": "This API key does not have permission to perform this action."
5  }
6}

Status Code: 403 Forbidden