Authentication

Agent Studio supports two authentication methods to accommodate different use cases.

Authentication Methods

Method	Use Case	Token Lifetime
JWT Bearer	User sessions, dashboard	30 min access, 7 day refresh
API Key	Server-to-server, integrations	No expiry (until revoked)

JWT Authentication

JWT (JSON Web Token) authentication is used for user sessions, typically from the dashboard or mobile apps.

Obtaining Tokens

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 1800
}

Using Access Tokens

Include the access token in the Authorization header:

GET /api/v1/agents
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Refreshing Tokens

Access tokens expire after 30 minutes. Use the refresh token to get a new access token:

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 1800
}

Token Payload

JWT tokens contain the following claims:

{
  "sub": "user-uuid",
  "tenant_id": "tenant-uuid",
  "type": "access",
  "scopes": ["agents:read", "agents:write"],
  "exp": 1705488600,
  "iat": 1705486800
}

API Key Authentication

API keys are used for server-to-server communication, webhooks, and automated integrations.

Key Formats

API keys are prefixed for easy identification:

Prefix	Environment	Use
`as_live_`	Production	Live data and calls
`as_test_`	Testing	Sandbox/staging

Example: as_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Creating API Keys

POST /api/v1/auth/api-keys
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "Production Integration",
  "environment": "live",
  "scopes": ["agents:read", "workflows:*", "calls:*"],
  "rate_limit": 500
}

Response:

{
  "key": "as_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "id": "key-uuid",
  "name": "Production Integration",
  "environment": "live",
  "scopes": ["agents:read", "workflows:*", "calls:*"],
  "rate_limit": 500,
  "created_at": "2026-01-17T10:30:00Z"
}

Security Note: The full API key is only returned once during creation. Store it securely - you cannot retrieve it again.

Using API Keys

Include the API key in the X-API-Key header:

GET /api/v1/agents
X-API-Key: as_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Managing API Keys

List Keys:

GET /api/v1/auth/api-keys

Revoke a Key:

DELETE /api/v1/auth/api-keys/{id}

Permission Scopes

Scopes control what resources an authenticated request can access.

Available Scopes

Scope	Description
`*`	Full access (admin)
`agents:read`	Read agents
`agents:write`	Create/update agents
`agents:delete`	Delete agents
`workflows:read`	Read workflows
`workflows:write`	Create/update workflows
`workflows:delete`	Delete workflows
`tools:read`	Read tools
`tools:write`	Create/update tools
`calls:read`	Read call history
`calls:write`	Initiate calls
`provider-keys:read`	Read provider keys
`provider-keys:write`	Manage provider keys

Wildcard Scopes

Use * suffix for all permissions on a resource:

agents:* = agents:read + agents:write + agents:delete
* = All permissions on all resources

Scope Validation

Requests are validated against the token's scopes:

# This requires agents:read scope
GET /api/v1/agents

# This requires agents:write scope
POST /api/v1/agents

# This requires agents:delete scope
DELETE /api/v1/agents/meal-agent

Security Best Practices

JWT Tokens

Store securely: Use httpOnly cookies or secure storage
Refresh proactively: Refresh before expiry to avoid interruptions
Handle expiry: Implement automatic refresh in your client
Logout properly: Clear tokens and call logout endpoint

API Keys

Never commit keys: Use environment variables
Rotate regularly: Create new keys periodically
Minimal scopes: Only request necessary permissions
Monitor usage: Check for unusual activity
Use test keys: Use as_test_* keys for development

General

Use HTTPS: Always use TLS in production
Validate inputs: Never trust client data
Log access: Monitor authentication attempts
Rate limit: Protect against brute force

Error Handling

Authentication Errors

HTTP Status	Code	Description
401	`authentication_error`	Invalid or missing credentials
401	`token_expired`	JWT token has expired
401	`invalid_token`	Token is malformed or invalid
401	`key_revoked`	API key has been revoked

Example Error Response:

{
  "error": {
    "code": "token_expired",
    "message": "Token has expired"
  }
}

Authorization Errors

HTTP Status	Code	Description
403	`authorization_error`	Insufficient permissions
403	`scope_required`	Missing required scope

Example Error Response:

{
  "error": {
    "code": "scope_required",
    "message": "This action requires the 'agents:write' scope"
  }
}

Code Examples

Python

import httpx

# With API Key
client = httpx.Client(
    base_url="https://api.agentstudio.dev/api/v1",
    headers={"X-API-Key": "as_live_xxx"}
)

agents = client.get("/agents").json()

JavaScript/TypeScript

// With JWT
const response = await fetch('https://api.agentstudio.dev/api/v1/agents', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const agents = await response.json();

cURL

# With API Key
curl -H "X-API-Key: as_live_xxx" \
  https://api.agentstudio.dev/api/v1/agents

# With JWT
curl -H "Authorization: Bearer eyJ..." \
  https://api.agentstudio.dev/api/v1/agents

Authentication

On this page