Authentication

Learn how to authenticate your API requests with Mindra Platform.

Overview

Mindra Platform uses API Key authentication for all API requests. API keys are tied to your user account and can be managed through the dashboard or programmatically.

API Key Format

All Mindra API keys follow this format:

mk_32_character_hexadecimal_string

Example:

mk_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p

Prefix: mk_ (Mindra Key)
Length: 35 characters total (3 char prefix + 32 char hash)
Character set: Lowercase hexadecimal (0-9, a-f)

Creating API Keys

Via Dashboard

Log in to console.mindra.co
Navigate to Settings > API Keys
Click Create New API Key
Configure your key:
- Name: Descriptive name (e.g., "Production", "Development")
- Permissions: Select which endpoints the key can access
- Expiration (optional): Set automatic expiration date
Click Create
Copy and store your key securely - it will only be shown once!

Via API

After initial authentication with your dashboard session:

curl -X POST https://api.mindra.co/v1/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "permissions": ["orchestrate", "agents:read", "executions:read"],
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

Response:

{
  "id": "key_123abc",
  "key": "mk_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
  "name": "Production API Key",
  "permissions": ["orchestrate", "agents:read", "executions:read"],
  "createdAt": "2025-11-10T10:00:00Z",
  "expiresAt": "2026-12-31T23:59:59Z",
  "isActive": true
}

Important: The key field is only returned once during creation. Store it securely!

Using API Keys

Include your API key in the Authorization header of every request:

Authorization: Bearer mk_your_api_key

cURL Example

curl https://api.mindra.co/v1/agents \
  -H "Authorization: Bearer mk_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p"

JavaScript Example

const MINDRA_API_KEY = 'mk_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p';

const response = await fetch('https://api.mindra.co/v1/orchestrate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${MINDRA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'Create an email campaign...',
    context: { ... }
  }),
});

const data = await response.json();

Python Example

import os
import requests

MINDRA_API_KEY = os.getenv('MINDRA_API_KEY')

headers = {
    'Authorization': f'Bearer {MINDRA_API_KEY}',
    'Content-Type': 'application/json',
}

response = requests.post(
    'https://api.mindra.co/v1/orchestrate',
    headers=headers,
    json={
        'query': 'Create an email campaign...',
        'context': { ... }
    }
)

data = response.json()

Go Example

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("MINDRA_API_KEY")

    payload := map[string]interface{}{
        "query": "Create an email campaign...",
        "context": map[string]interface{}{ ... },
    }

    jsonPayload, _ := json.Marshal(payload)

    req, _ := http.NewRequest(
        "POST",
        "https://api.mindra.co/v1/orchestrate",
        bytes.NewBuffer(jsonPayload),
    )

    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

API Key Permissions

Control what each API key can access:

Permission	Description	Endpoints
`orchestrate`	Execute orchestration requests	`POST /v1/orchestrate`
`agents:read`	List and view agents	`GET /v1/agents`
`agents:write`	Register custom agents	`POST /v1/agents`
`executions:read`	View execution status	`GET /v1/executions/:id`
`executions:cancel`	Cancel running executions	`POST /v1/executions/:id/cancel`
`api-keys:manage`	Create/delete API keys	`POST /v1/api-keys`

Permission Examples

Production Key (minimal permissions):

{
  "name": "Production",
  "permissions": ["orchestrate", "executions:read"]
}

Admin Key (full access):

{
  "name": "Admin",
  "permissions": [
    "orchestrate",
    "agents:read",
    "agents:write",
    "executions:read",
    "executions:cancel",
    "api-keys:manage"
  ]
}

Managing API Keys

List All Keys

curl https://api.mindra.co/v1/api-keys \
  -H "Authorization: Bearer mk_your_api_key"

Response:

{
  "keys": [
    {
      "id": "key_123abc",
      "name": "Production",
      "permissions": ["orchestrate", "executions:read"],
      "createdAt": "2025-11-10T10:00:00Z",
      "lastUsedAt": "2025-11-10T15:30:00Z",
      "isActive": true
    },
    {
      "id": "key_456def",
      "name": "Development",
      "permissions": ["orchestrate", "agents:read"],
      "createdAt": "2025-11-09T08:00:00Z",
      "lastUsedAt": null,
      "isActive": true
    }
  ]
}

Note: The actual key value is never returned after creation.

Deactivate a Key

curl -X PATCH https://api.mindra.co/v1/api-keys/key_123abc \
  -H "Authorization: Bearer mk_your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

Delete a Key

curl -X DELETE https://api.mindra.co/v1/api-keys/key_123abc \
  -H "Authorization: Bearer mk_your_admin_key"

Warning: Deletion is permanent and immediate. All requests using this key will fail immediately.

Security Best Practices

1. Store Keys Securely

DO:

Use environment variables
Use secret management systems (AWS Secrets Manager, HashiCorp Vault)
Encrypt keys at rest

DON'T:

Hard-code keys in source code
Commit keys to version control
Share keys via email or chat
Log keys in application logs

2. Use Key Rotation

Rotate API keys regularly:

# 1. Create new key
NEW_KEY=$(curl -X POST https://api.mindra.co/v1/api-keys \
  -H "Authorization: Bearer $OLD_KEY" \
  -d '{"name": "Production-v2"}' | jq -r '.key')

# 2. Update your application to use new key
export MINDRA_API_KEY=$NEW_KEY

# 3. Deactivate old key after verifying new key works
curl -X PATCH https://api.mindra.co/v1/api-keys/key_old \
  -H "Authorization: Bearer $NEW_KEY" \
  -d '{"isActive": false}'

3. Use Minimal Permissions

Follow the principle of least privilege:

// Production API - only needs orchestration
const prodKey = 'mk_prod_...'; // permissions: ["orchestrate", "executions:read"]

// Admin dashboard - needs full access
const adminKey = 'mk_admin_...'; // permissions: ["*"]

// Analytics service - read-only
const analyticsKey = 'mk_analytics_...'; // permissions: ["executions:read", "agents:read"]

4. Set Expiration Dates

For temporary access:

curl -X POST https://api.mindra.co/v1/api-keys \
  -H "Authorization: Bearer mk_your_key" \
  -d '{
    "name": "Partner Demo Access",
    "permissions": ["orchestrate"],
    "expiresAt": "2025-12-01T00:00:00Z"
  }'

5. Monitor Key Usage

Check key activity regularly:

curl https://api.mindra.co/v1/api-keys/key_123abc/activity \
  -H "Authorization: Bearer mk_your_key"

Response:

{
  "keyId": "key_123abc",
  "lastUsedAt": "2025-11-10T15:30:00Z",
  "usageStats": {
    "last24h": 1247,
    "last7d": 8932,
    "last30d": 35641
  },
  "recentRequests": [
    {
      "timestamp": "2025-11-10T15:30:00Z",
      "endpoint": "/v1/orchestrate",
      "method": "POST",
      "statusCode": 202,
      "ipAddress": "203.0.113.42"
    }
  ]
}

6. IP Whitelisting (Enterprise)

Restrict keys to specific IP addresses:

curl -X POST https://api.mindra.co/v1/api-keys \
  -H "Authorization: Bearer mk_your_key" \
  -d '{
    "name": "Office Only",
    "permissions": ["orchestrate"],
    "ipWhitelist": ["203.0.113.0/24", "198.51.100.42"]
  }'

Rate Limits

API keys are subject to rate limits based on your account tier:

Tier	Requests/Minute	Requests/Day
Developer	100	10,000
Business	500	100,000
Enterprise	Custom	Custom

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699632000

Handling Rate Limits

When you hit the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Try again in 42 seconds.",
  "retryAfter": 42,
  "limit": 100,
  "resetAt": "2025-11-10T15:31:00Z"
}

Implement exponential backoff:

import time
import requests

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            wait_time = min(retry_after, 2 ** attempt * 10)
            time.sleep(wait_time)
            continue

        return response

    raise Exception("Max retries exceeded")

Error Responses

401 Unauthorized

Invalid or missing API key:

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "details": "Ensure your API key is included in the Authorization header"
}

Causes:

API key not included in request
API key format is invalid
API key has been deactivated or deleted

403 Forbidden

Insufficient permissions:

{
  "error": "FORBIDDEN",
  "message": "Insufficient permissions",
  "details": "This API key does not have 'agents:write' permission",
  "requiredPermission": "agents:write"
}

Solution: Create a new key with appropriate permissions or use a different key.

401 Unauthorized (Expired)

API key expired:

{
  "error": "KEY_EXPIRED",
  "message": "API key has expired",
  "expiredAt": "2025-10-31T23:59:59Z",
  "details": "Create a new API key at https://console.mindra.co/settings/api-keys"
}

Testing Authentication

Test your API key:

curl https://api.mindra.co/v1/auth/test \
  -H "Authorization: Bearer mk_your_api_key"

Response:

{
  "authenticated": true,
  "keyId": "key_123abc",
  "keyName": "Production",
  "permissions": ["orchestrate", "executions:read"],
  "userId": "user_456def",
  "accountTier": "ENTERPRISE"
}

Support

Having authentication issues? Contact us:

Documentation: docs.mindra.co
Support: info@mindra.co
Security: info@mindra.co

Next: Quick Start Guide →