Authentication

Authentication

Intellia API supports two authentication methods: API Keys for server-to-server communication and JWT tokens for user-authenticated requests.

API Key Authentication

API keys are the recommended way to authenticate programmatic access to the Intellia API. They can be created in the Organization > API Keys section.

Creating an API Key

1. Navigate to Organization > API Keys in the UI
2. Click Create API Key
3. Provide a Description (required) - e.g., “Production Integration”
4. The system will generate an API key

Permissions Model

When creating an API key, you can grant permissions to specific resources. The permission structure follows this pattern:

{
  "resource_name": {
    "read": boolean,
    "write": boolean
  }
}

Available permission scopes include:

• agents - Read/Write agent configurations
• conversations - Read/Write conversations
• knowledge_bases - Read/Write knowledge bases
• tools - Read/Write tool attachments
• integrations - Read/Write integrations
• prompts - Read/Write prompts
• assume_role - Generate assume-role tokens
• webhooks - Manage webhooks

Using API Keys in Requests

Include the API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.intellia.com.au/orgs/{organizationId}/agents

API Key Features

API Key Limitations

The following operations cannot be performed with API keys (these require user authentication):

• Creating, listing, or managing API keys themselves
• Billing and subscription operations
• Assume-role token generation (unless specifically permitted)

Assume Role Tokens

For scenarios where you need to generate temporary authentication tokens for end-users (e.g., embedding chat widgets), use the assume-role endpoint.

POST /orgs/{organizationId}/assume-role

Required: API key with assume_role write permission

Request Body:

{
  "userId": "user-123",
  "userEmail": "user@example.com",
  "userName": "John Doe"
}

Response:

{
  "token": "eyJhbGci...",
  "expiresAt": "2024-01-01T12:00:00Z",
  "userId": "user-123",
  "organizationId": "org-456",
  "role": "chat"
}

Features:

• Users are automatically created if they don’t exist
• New users are assigned to the Default user group
• Tokens expire after 2 hours
• Ideal for frontend chat widgets and embedded applications

Best Practices

1. Never expose API keys in frontend code - Always proxy through your backend
2. Use specific permissions - Grant only the minimum permissions needed
3. Rotate keys regularly - Create new keys and delete old ones periodically
4. Use assume-role for end users - Generate short-lived tokens instead of sharing API keys