Docs/Authentication

Authentication

Jarvis SDK supports two authentication methods: API key authentication (recommended for agents) and OAuth 2.1 bearer tokens (for user-facing applications).

Overview

Method	Header	Best For
API Key	x-api-key: jsk_...	Agents, scripts, server-to-server
OAuth 2.1 Bearer	Authorization: Bearer eyJ...	User-facing apps, dashboards

API Key Authentication

API keys are the primary authentication method for AI agents. Each key is scoped to a tenant and carries the tenant's plan limits. Keys are prefixed with jsk_.

Creating an API Key

# Register a new tenant and get an API key
curl -X POST https://jarvissdk.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "My Production Agent",
    "owner_email": "agent@example.com"
  }'

# Response:
{
  "api_key": "jsk_...",
  "tenant_id": "335619a3-...",
  "plan": "free",
  "limits": { "modules": 10, "executions_per_month": 1000 }
}

Using the API Key

Pass the key in the x-api-key header on every request:

curl

curl https://jarvissdk.com/api/v1/modules \
  -H "x-api-key: jsk_802b6db28ff84154bf912a01"

TypeScript

const response = await fetch('https://jarvissdk.com/api/v1/modules', {
  headers: { 'x-api-key': process.env.JARVIS_API_KEY! }
});
const modules = await response.json();

Python

import httpx, os

resp = httpx.get(
    "https://jarvissdk.com/api/v1/modules",
    headers={"x-api-key": os.environ["JARVIS_API_KEY"]}
)
modules = resp.json()

API Key Management

Create Additional Keys

Each tenant can have multiple API keys with different scopes (Pro plan and above).

curl -X POST https://jarvissdk.com/api/v1/keys \
  -H "x-api-key: jsk_your_primary_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staging-key",
    "scopes": ["modules:read", "modules:execute"]
  }'

# Response:
{
  "key_id": "key_abc123",
  "api_key": "jsk_new_key_here",
  "name": "staging-key",
  "scopes": ["modules:read", "modules:execute"],
  "created_at": "2026-03-04T12:00:00Z"
}

Available Scopes

Scope	Permissions
modules:read	Browse, search, and get module details
modules:execute	Execute module actions
modules:install	Install and uninstall modules
modules:write	Publish and update your own modules
billing:read	View usage and billing information
keys:manage	Create and revoke API keys
memory:read	Read agent memory entries
memory:write	Store and update agent memory
*	Full access (default for primary key)

Key Rotation

Rotate keys without downtime by creating a new key before revoking the old one.

# 1. Create new key
curl -X POST https://jarvissdk.com/api/v1/keys \
  -H "x-api-key: jsk_old_key" \
  -d '{"name": "rotated-key-march"}'

# 2. Update your agent's config to use the new key

# 3. Revoke the old key
curl -X DELETE https://jarvissdk.com/api/v1/keys/key_old_id \
  -H "x-api-key: jsk_new_key"

OAuth 2.1 Bearer Tokens

For user-facing applications (dashboards, web apps), Jarvis SDK supports OAuth 2.1 with Supabase Auth. Users sign in with email/password or social providers, and the JWT is passed as a Bearer token.

# Sign in to get a session token
curl -X POST https://baqidfivdszhabboeyta.supabase.co/auth/v1/token?grant_type=password \
  -H "apikey: YOUR_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret"}'

# Use the access_token as Bearer
curl https://jarvissdk.com/api/v1/modules \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Note: OAuth tokens expire. For long-running agents, use API key authentication instead. API keys do not expire unless explicitly revoked.

Public Endpoints

These endpoints do not require authentication:

Endpoint	Purpose
GET /api/v1/health	Platform health check
GET /api/llms.txt	LLM-friendly module documentation
GET /api/openapi.json	OpenAPI 3.1 specification
GET /.well-known/agent.json	A2A Agent Card
POST /api/v1/auth/register	Create new tenant (returns API key)

Rate Limiting

Rate limits are enforced per API key and vary by plan:

Plan	Requests/min	Executions/month
Free	60	1,000
Pro ($29/mo)	300	50,000
Business ($299/mo)	1,000	500,000
Enterprise	Custom	Unlimited

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Security Best Practices

Store API keys in environment variables, never in source code

Use scoped keys with minimum required permissions

Rotate keys regularly (monthly recommended for production)

Monitor the Usage dashboard for unexpected activity

Use separate keys for development, staging, and production

Revoke compromised keys immediately via the dashboard or API

Error Responses

Code	Meaning	Action
401	Missing or invalid API key	Check the x-api-key header
403	Insufficient scope	Create a key with the required scope
429	Rate limit exceeded	Wait for X-RateLimit-Reset, then retry

← Getting Started Module Format →