Skip to main content

​
Overview

The Junis External API uses API Keys for authentication. All API requests must include a valid API key in the X-API-Key header.
API keys are organization-scoped. Each key belongs to a specific organization and can only access that organization’s resources.

​
API Key Authentication

​
Creating an API Key

1

Navigate to API Keys Page

Go to Dashboard → API Keys in the Junis dashboard
2

Click Create New API Key

Click the ”+ Create API Key” buttonFill in the form:
  • Name: A descriptive name for the key (e.g., “Production API”, “Testing”)
  • Description: Optional notes about the key’s purpose
  • Scopes: Select permissions (default: all external API scopes enabled)
  • Rate Limits: Configure requests per minute/hour (optional)
3

Copy the API Key

IMPORTANT: The API key will only be shown once. Copy it immediately and store it securely.
The key format is: jns_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX (32 random characters)

​
API Key Format

PrefixPurposeExample
jns_live_Production keysjns_live_abc123... (32 chars)
API keys are hashed using bcrypt before storage. The plaintext key cannot be retrieved after creation.

​
Using API Keys

Include your API key in the X-API-Key header:
cURL
curl -X POST https://api.junis.ai/api/external/v1/chat/completions \
  -H "X-API-Key: jns_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

​
API Key Permissions (Scopes)

​
Available Scopes

API keys can have granular permissions. Each scope grants access to specific API operations:
ScopeDescriptionRequired For
orchestrator:invokeInvoke orchestrator with prompts (non-streaming)Chat Completions (non-streaming)
orchestrator:streamStream orchestrator responses (SSE)Chat Completions (streaming)
sessions:readRead chat sessionsList sessions, Get session status
sessions:messagesRead session messagesGet session messages
content:readRead generated contentList content, Get content detail
content:retryRetry failed content generationRetry content generation
agents:listList available agents in organizationList agents
agents:invokeInvoke specific agents directlyAgent completions
admin:readRead admin resources (organization-scoped)Admin endpoints (if accessible)
admin:writeWrite admin resources (organization-scoped)Admin endpoints (if accessible)
Default Scopes: New API keys are created with the following scopes enabled by default:
  • orchestrator:invoke
  • orchestrator:stream
  • sessions:read
  • sessions:messages
  • agents:list
  • agents:invoke
For content generation access (content:read, content:retry), you need to explicitly enable these scopes when creating or updating a key.

​
Scope Requirements by Endpoint

EndpointRequired Scopes
POST /api/external/v1/chat/completions (non-streaming)orchestrator:invoke
POST /api/external/v1/chat/completions (streaming)orchestrator:invoke, orchestrator:stream
GET /api/external/sessionssessions:read
GET /api/external/sessions/{id}/messagessessions:messages
GET /api/external/sessions/{id}/statussessions:read
GET /api/external/contentcontent:read
GET /api/external/content/{id}content:read
POST /api/external/content/{id}/retrycontent:retry
GET /api/external/agentsagents:list
POST /api/external/agents/{id}/completions (non-streaming)agents:invoke
POST /api/external/agents/{id}/completions (streaming)agents:invoke

​
Rate Limits

API keys are subject to rate limits to ensure fair usage and system stability.

​
Default Rate Limits

Limit TypeDefault ValueCustomizable
Requests per minute100Yes (when creating API key)
Requests per hour1,000Yes (when creating API key)
Rate limits are configurable per API key. Contact your organization admin to adjust limits if needed.

​
Rate Limit Headers

All API responses include rate limit information in headers: 
X-RateLimit-Limit-Minute: 100
X-RateLimit-Remaining-Minute: 85
X-RateLimit-Reset-Minute: 1704988800
X-RateLimit-Limit-Hour: 1000
X-RateLimit-Remaining-Hour: 950
X-RateLimit-Reset-Hour: 1704992400
See Rate Limits for detailed documentation.

​
Security Best Practices

  • Never commit API keys to Git repositories
  • Store keys in environment variables or secret management systems (e.g., AWS Secrets Manager, HashiCorp Vault)
  • Use .env files for local development (add to .gitignore)
  • Rotate keys regularly (every 90 days recommended)
  • All API requests must use HTTPS
  • Never send API keys over unencrypted HTTP
  • Our API automatically rejects non-HTTPS requests
  • Create separate keys for development, staging, and production
  • Use descriptive names to identify key purposes (e.g., “Prod - Web App”, “Dev - Testing”)
  • Revoke unused keys immediately
  • Check the API Keys page for usage statistics
  • Review last_used_at and request_count regularly
  • Set up alerts for unusual activity (e.g., sudden spike in requests)
If an API key is compromised:
  1. Immediately revoke the key in Admin → API Keys
  2. Create a new key with a different name
  3. Update all applications to use the new key
  4. Review logs for suspicious activity (unusual endpoints, high request counts)
  • Only grant scopes that are actually needed
  • For read-only integrations, use sessions:read and sessions:messages only
  • Avoid granting admin:write unless absolutely necessary

​
Error Handling

​
Common Authentication Errors

{
  "detail": "API key required. Include X-API-Key header with your request."
}

​
Handling Errors in Code

When you receive an error response, check the HTTP status code and error message to determine the cause. Common error codes:
  • 401 Unauthorized: Invalid or missing API key
  • 403 Forbidden: Insufficient scopes/permissions
  • 429 Too Many Requests: Rate limit exceeded (wait for retry_after seconds)

​
Next Steps

Chat Completions API

Start sending messages to your agents

Sessions API

Retrieve and manage chat sessions

Rate Limits

Understand rate limiting and best practices

Error Codes

Full list of error codes and solutions