Skip to main content
All Orchestrator API requests require authentication. We support two authentication methods depending on your use case.

​
API Key Authentication

Recommended for programmatic access and automation scripts. API keys provide secure, long-term access to the Orchestrator API. They’re perfect for server-side applications, automation scripts, and CI/CD pipelines.

​
Getting Your API Key

  1. Log in to your Orchestrator dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key and give it a descriptive name
  4. Copy and securely store your API key
API keys provide full access to your account. Store them securely and never commit them to version control.

​
Using API Keys

Include your API key in the Authorization header of every request: 
curl https://api.orchestratorhq.com/api/sessions \
  -H "Authorization: Bearer orch_your_api_key_here"

​
API Key Format

API keys follow this format: 
orch_1234567890abcdef1234567890abcdef12345678
  • Always start with orch_
  • Followed by 40 hexadecimal characters
  • Case-sensitive

​
JWT Token Authentication

Used by the web dashboard and browser-based applications. JWT tokens are short-lived tokens used primarily by the Orchestrator web dashboard. They’re automatically managed by the browser and typically not used for direct API integration.

​
Token Format

JWT tokens are included in the Authorization header: 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
JWT tokens expire after a set period and are automatically refreshed by the web dashboard. For programmatic access, use API keys instead.

​
Authentication Errors

When authentication fails, the API returns a 401 Unauthorized response: 
{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "code": 401
}

​
Common Authentication Issues

Error: Invalid API key formatSolution: Ensure your API key starts with orch_ and is exactly 45 characters long.
Error: API key not foundSolution: Verify the API key exists in your dashboard and hasn’t been deleted.
Error: Missing authorization headerSolution: Include the Authorization: Bearer your_api_key header in your request.
Error: Token expiredSolution: Refresh your browser session or use an API key for programmatic access.

​
Security Best Practices

Secure Storage

Store API keys in environment variables or secure credential stores, never in code.

Rotate Regularly

Rotate API keys periodically and immediately if compromised.

Principle of Least Privilege

Create separate API keys for different applications with descriptive names.

Monitor Usage

Monitor API key usage in your dashboard to detect unauthorized access.

​
Environment Variables

Store your API key securely using environment variables: 
ORCHESTRATOR_API_KEY=orch_your_api_key_here

​
Next Steps

Now that you understand authentication, you’re ready to create your first browser session:

Create Your First Session

Learn how to create and configure browser sessions