Authentication

Overview

The Unleeshed Partner API uses API Key authentication for all server-to-server requests. API keys are issued to licensed partners and provide secure access to your licensed personas and commentary generation.

Getting Your API Key

Log into the Partner Dashboard
Navigate to Developer → API Keys
Click Create API Key
Select the required scopes (permissions)
Copy and securely store the key

API keys are only shown once when created. Store them securely in your environment variables or secrets manager.

Using Your API Key

Include the API key in the X-Api-Key header for all requests:

curl -X GET "https://prod.api.unleeshed.ai/partner/v1/personas" \
  -H "X-Api-Key: pk_live_abc123..."

const response = await fetch('https://prod.api.unleeshed.ai/partner/v1/personas', {
  headers: {
    'X-Api-Key': process.env.UNLEESHED_API_KEY
  }
});

import os
import requests

response = requests.get(
    "https://prod.api.unleeshed.ai/partner/v1/personas",
    headers={"X-Api-Key": os.environ["UNLEESHED_API_KEY"]}
)

API Key Scopes

API keys have granular scopes that control what actions they can perform:

Scope	Description	Endpoints
`personas:read`	View licensed personas	`GET /personas`, `GET /personas/:id`
`topics:submit`	Create topics for commentary	`POST /topics`
`topics:read`	View topic status and results	`GET /topics`, `GET /topics/:id`
`usage:read`	View usage statistics	`GET /usage`

Follow the principle of least privilege. Only grant the scopes your integration actually needs.

Key Format

API keys follow this format:

pk_[environment]_[random_string]

Examples:
- pk_live_abc123...  (Production)
- pk_test_xyz789...  (Sandbox/Testing)

Security Best Practices

Never expose keys in client-side code

API keys should only be used in server-side code. Never include them in:

JavaScript bundles served to browsers
Mobile app source code
Public repositories
Client-side environment variables

Use environment variables

Store API keys in environment variables or a secrets manager:

# .env (never commit this file!)
UNLEESHED_API_KEY=pk_live_abc123...

// Access in your code
const apiKey = process.env.UNLEESHED_API_KEY;

Rotate keys periodically

Rotate your API keys every 90 days or immediately if you suspect compromise:

Create a new API key in the dashboard
Update your application to use the new key
Verify the new key works
Revoke the old key

Use IP restrictions (optional)

For additional security, restrict your API key to specific IP addresses:

Go to Developer → API Keys
Click on your key
Add allowed IP addresses

Requests from non-whitelisted IPs will be rejected.

Error Responses

Authentication errors return a 401 status code:

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Common authentication errors:

Error Code	Description	Solution
`unauthorized`	Missing or invalid API key	Check that you’re including the `X-Api-Key` header
`key_revoked`	API key has been revoked	Create a new API key in the dashboard
`key_expired`	API key has expired	Create a new API key or contact support
`ip_restricted`	Request from non-whitelisted IP	Add your IP to the allowed list
`scope_denied`	Key lacks required scope	Create a new key with the needed scopes

Rate Limiting

API keys are subject to rate limits:

Tier	Rate Limit	Burst
Standard	1,000 requests/hour	100 requests/minute
Premium	5,000 requests/hour	500 requests/minute

When rate limited, you’ll receive a 429 response with a Retry-After header.

Get Started

Core Concepts

Guides

Resources

Overview

Getting Your API Key

Using Your API Key

API Key Scopes

Key Format

Security Best Practices

Error Responses

Rate Limiting

Next Steps

Create Your First Topic

API Reference

​Overview

​Getting Your API Key

​Using Your API Key

​API Key Scopes

​Key Format

​Security Best Practices

​Error Responses

​Rate Limiting

​Next Steps

Create Your First Topic

API Reference

Overview

Getting Your API Key

Using Your API Key

API Key Scopes

Key Format

Security Best Practices

Error Responses

Rate Limiting

Next Steps