Skip to main content

​
Overview

Omnara uses API keys for authentication. You can obtain an API key through browser-based OAuth or by manually copying it from your dashboard.

​
First-Time Setup

omnara --auth
This command:
  1. Starts a local HTTP server on a random port
  2. Opens your browser to https://omnara.com/cli-auth
  3. Prompts you to sign in (or create an account)
  4. Automatically receives the API key via callback
  5. Saves the key to ~/.omnara/credentials.json
The local server only listens on 127.0.0.1 and shuts down after authentication for security.

​
Option 2: Manual API Key

If browser authentication doesn’t work (e.g., remote SSH session):
1

Get Your API Key

  1. Sign in to your account at omnara.com
  2. Navigate to Account → API Keys (bottom left of dashboard)
  3. Or visit directly: omnara.com/dashboard/api-keys
  4. Click Create API Key or copy an existing key
2

Set the API Key

Choose one method:
export OMNARA_API_KEY="xxxxxxxxxxxxxxxxxxxx"
omnara

​
Re-authentication

If your API key expires or you need to switch accounts: 
omnara --reauth
This forces a new authentication flow even if credentials already exist.

​
How It Works

​
Browser Authentication Flow

1

CLI Starts Local Server

Generates a secure random state parameter and starts HTTP server on 127.0.0.1:random_port
2

Browser Opens

URL includes port and state: https://omnara.com/cli-auth?port=12345&state=abc123...
3

User Authenticates

Signs in with Omnara account (creates account if first time)
4

Backend Generates API Key

Server generates a JWT token with your user_id and returns it to the web page
5

Callback to CLI

Web page sends API key back to local CLI via:
  • Local sessions: Hidden iframe to http://127.0.0.1:{port}/?api_key={key}&state={state}
  • Remote sessions: User copies key manually
6

Key Saved

CLI validates state parameter, saves key to ~/.omnara/credentials.json with 0o600 permissions

​
Authentication Priority

When you run a command, Omnara looks for credentials in this order:
  1. --api-key flag (highest priority)
  2. OMNARA_API_KEY environment variable
  3. ~/.omnara/credentials.json file
  4. Triggers authentication if none found

​
Example

# All three set different keys
export OMNARA_API_KEY="env_key"
# credentials.json contains "file_key"
omnara --api-key "flag_key"

# Uses "flag_key" because flags have highest priority

​
Storage Locations

​
Credentials File

Path: ~/.omnara/credentials.json Format: 
{
  "write_key": "xxxxxxxxxxxxxxxxxxxx"
}
Permissions: 0o600 (owner read/write only)
Never commit this file to version control! Add ~/.omnara/ to your .gitignore.

​
Configuration File

Path: ~/.omnara/config.json Format: 
{
  "default_agent": "claude"
}
Purpose: Non-sensitive settings (default agent, preferences)

​
API Key Format

Omnara API keys are JWT tokens with this structure:
  • Format: Base64-encoded JWT (no prefix)
  • Algorithm: RS256 (RSA with SHA-256)
  • Claims:
    • sub: Your user ID
    • iat: Issued at timestamp
    • No expiration (valid indefinitely)
Omnara uses weaker RSA keys intentionally to keep API keys shorter. Keep your keys secure despite this tradeoff.

​
Security Best Practices

Don’t store credentials in CI/CD configuration files:
# GitHub Actions
- name: Run Omnara
  env:
    OMNARA_API_KEY: ${{ secrets.OMNARA_API_KEY }}
  run: omnara headless --prompt "Run tests"
Generate new API keys from your dashboard every few months:
# Get new key from dashboard, then:
omnara --reauth
Create multiple API keys in your dashboard:
  • Development key
  • Production key
  • CI/CD key
This allows you to revoke specific keys without affecting others.
Ensure your scripts don’t accidentally log credentials:
# Bad: logs API key
echo "Using key: $OMNARA_API_KEY"

# Good: logs without revealing key
echo "Using key: ${OMNARA_API_KEY:0:10}..."

​
Troubleshooting

If webbrowser.open() fails:
omnara --auth
# Copy the URL from terminal output
# Manually open it in your browser
If authentication times out after 5 minutes:
# Try again
omnara --auth

# Or use manual method
# 1. Visit https://omnara.com/cli-auth
# 2. Copy API key
# 3. Paste when CLI prompts
If you see JSON parsing errors:
# Check file contents
cat ~/.omnara/credentials.json

# If corrupt, re-authenticate
rm ~/.omnara/credentials.json
omnara --auth
If you can’t read credentials:
# Fix permissions
chmod 600 ~/.omnara/credentials.json

# Fix directory
chmod 700 ~/.omnara
If authentication fails with valid-looking key:
# Key may be revoked or expired
# Generate new key from dashboard
omnara --reauth

​
Advanced Usage

​
Self-Hosted Instances

Point to your own Omnara instance: 
omnara --auth --auth-url https://omnara.mycompany.com
This uses your custom authentication URL while keeping the same flow.

​
Programmatic API Key Management

For automation, you can manage credentials programmatically: 
import json
from pathlib import Path

# Read API key
creds_path = Path.home() / ".omnara" / "credentials.json"
with open(creds_path) as f:
    api_key = json.load(f)["write_key"]

# Use in your scripts
import os
os.environ["OMNARA_API_KEY"] = api_key

Environment Variables

Configure Omnara with environment variables

Configuration Files

Learn about all configuration files