Authentication

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.

Junis has two kinds of API keys: organization keys (jns_live_) bound to a single organization, and user keys (jns_user_) that work across all organizations you belong to. See Organization vs User API Keys below.

API Key Authentication

Creating an API Key

Navigate to API Keys Page

Go to Dashboard → API Keys in the Junis dashboard

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)

Copy the API Key

IMPORTANT: Copy the API key and store it securely. Treat it like a password — anyone with the key can act with its permissions.

The key format is: jns_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX (32 random characters)

API Key Format

Prefix	Purpose	Where to Create
`jns_live_`	Organization key — bound to one organization	Admin → API Keys (admin/owner)
`jns_user_`	User key — works across all your organizations	Settings → API Keys (up to 5 per user)

Organization vs User API Keys

Organization keys (jns_live_) always act within the organization they were created in.
User keys (jns_user_) act as you, across every organization you belong to. Select which organization a request targets with the X-Organization-Id header; if omitted, your current organization is used.

cURL — user key targeting a specific organization

curl -X POST https://api.junis.ai/api/external/v1/chat/completions \
  -H "X-API-Key: jns_user_YOUR_API_KEY_HERE" \
  -H "X-Organization-Id: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello!"}]}'

User keys are what Junis Magic uses — one key, all your squads.

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:

Scope	Description	Required For
`orchestrator:invoke`	Invoke orchestrator with prompts (non-streaming)	Chat Completions (non-streaming)
`orchestrator:stream`	Stream orchestrator responses (SSE)	Chat Completions with `stream: true`
`sessions:read`	Read chat sessions	List sessions, Get session status
`sessions:messages`	Read session messages	Get session messages
`content:read`	Read generated content	List content, Get content detail
`content:retry`	Retry failed content generation	Retry content generation
`agents:list`	List available agents in organization	List agents
`agents:invoke`	Invoke specific agents directly	Agent completions
`rag:upload`	Upload files to RAG Datastore	Create DataStore, Upload files
`rag:read`	Read RAG uploads and DataStores	List DataStores, List uploads, Get upload status
`rag:delete`	Delete RAG uploads and documents (opt-in, never default)	Delete RAG resources
`sessions:delete`	Delete a session and its messages (opt-in, never default)	Delete a session
`admin:read`	Read admin resources (organization-scoped)	Admin endpoints (if accessible)
`admin:write`	Write admin resources (organization-scoped)	Admin endpoints (if accessible)
`users:provision`	Provision (create-or-get) users and pending org memberships	User Provisioning
`users:delegate`	Act on behalf of another organization member	`on_behalf_of` on chat/agent completions and on session read & delete

Default Scopes: Organization keys created from the dashboard include: orchestrator:invoke, orchestrator:stream, sessions:read, sessions:messages, agents:list, agents:invoke, content:read, content:retry.User keys include a broader default set covering management operations (used by Junis Magic). Additional scopes — RAG and delete — are granted by updating the key (ask your organization admin). For partner scopes, see below.

Updating scopes replaces the whole list. Send every scope the key should keep, not just the ones you are adding. Unknown scope names are rejected so a typo cannot leave a key permanently locked out, and an empty list is refused unless you explicitly confirm it — to disable a key, deactivate it instead of stripping its scopes.

Partner scopes are opt-in only: users:provision, users:delegate and sessions:delete are never included in any default scope set, and are intended for trusted partner services that manage end-user accounts.To get them, create an organization key from Dashboard → API Keys → New Key with “Connect users from my own app” ticked. A key created without that checkbox does not carry them. See User Provisioning.

Scope Requirements by Endpoint

Endpoint	Required 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/sessions`	`sessions:read`
`GET /api/external/sessions/{id}/messages`	`sessions:messages`
`GET /api/external/sessions/{id}/status`	`sessions:read`
`GET /api/external/content`	`content:read`
`GET /api/external/content/{id}`	`content:read`
`POST /api/external/content/{id}/retry`	`content:retry`
`GET /api/external/agents`	`agents:list`
`POST /api/external/agents/{id}/completions` (non-streaming)	`agents:invoke`
`POST /api/external/agents/{id}/completions` (streaming)	`agents:invoke`
`POST /api/external/rag/datastores`	`rag:upload`
`GET /api/external/rag/datastores`	`rag:read`
`POST /api/external/rag/upload`	`rag:upload`
`POST /api/external/management/users`	`users:provision`
`POST /api/external/v1/chat/completions` with `on_behalf_of`	`orchestrator:invoke`, `users:delegate`
`GET /api/external/sessions` with `on_behalf_of`	`sessions:read`, `users:delegate`
`GET /api/external/sessions/{id}/messages` with `on_behalf_of`	`sessions:messages`, `users:delegate`
`DELETE /api/external/sessions/{id}`	`sessions:delete`
`DELETE /api/external/sessions/{id}` with `on_behalf_of`	`sessions:delete`, `users:delegate`
`GET /api/external/rag/uploads`	`rag:read`
`GET /api/external/rag/uploads/{id}`	`rag:read`

Rate Limits

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

Default Rate Limits

Limit Type	Default Value	Customizable
Requests per minute	100	Yes (when creating API key)
Requests per hour	1,000	Yes (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: 1767261600
X-RateLimit-Limit-Hour: 1000
X-RateLimit-Remaining-Hour: 950
X-RateLimit-Reset-Hour: 1767265200

See Rate Limits for detailed documentation.

Security Best Practices

Keep API Keys Secret

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)

Use HTTPS Only

All API requests must use HTTPS
Never send API keys over unencrypted HTTP
Our API automatically rejects non-HTTPS requests

Separate Keys for Different Environments

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

Monitor Key Usage

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)

Revoke Compromised Keys

If an API key is compromised:

Immediately revoke the key in Admin → API Keys
Create a new key with a different name
Update all applications to use the new key
Review logs for suspicious activity (unusual endpoints, high request counts)

Principle of Least Privilege

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."
}

{
  "detail": "Invalid or expired API key"
}

{
  "error": "insufficient_scopes",
  "message": "API key does not have required permissions",
  "required_scopes": ["sessions:delete"],
  "missing_scopes": ["sessions:delete"],
  "available_scopes": ["orchestrator:invoke", "sessions:read"]
}

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded. Please try again in 60 seconds.",
    "code": "rate_limit_exceeded",
    "retry_after": 60
  }
}

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

​Overview

​API Key Authentication

​Creating an API Key

​API Key Format

​Organization vs User API Keys

​Using API Keys

​API Key Permissions (Scopes)

​Available Scopes

​Scope Requirements by Endpoint

​Rate Limits

​Default Rate Limits

​Rate Limit Headers

​Security Best Practices

​Error Handling

​Common Authentication Errors

​Handling Errors in Code

​Next Steps

Chat Completions API

Sessions API

Rate Limits

Error Codes

Overview

API Key Authentication

Creating an API Key

API Key Format

Organization vs User API Keys

Using API Keys

API Key Permissions (Scopes)

Available Scopes

Scope Requirements by Endpoint

Rate Limits

Default Rate Limits

Rate Limit Headers

Security Best Practices

Error Handling

Common Authentication Errors

Handling Errors in Code

Next Steps