interlocute.ai beta
+Node

Auth & Keys

How authentication works, how to obtain and manage API keys, and best practices for secure setup.

How authentication works

All API requests to Interlocute are authenticated using bearer tokens. Include your API key in the Authorization header of every request: 

Authorization: Bearer YOUR_API_KEY

Requests without a valid key return 401 Unauthorized. Requests with a valid key that lacks the required scope return 403 Forbidden.

Authentication for invocation cancellation

POST /chit/{invocationId}/cancel and the external-ID cancellation route always require a bearer token, even when the node permits anonymous Chit reads. An invocation ID is not a credential. Your tenant API key must belong to the node's tenant and satisfy its Node scope and allowed-origin checks.

JWT callers must be authorized tenant members; a signed-in session alone does not grant access to another tenant's work. Missing or invalid authentication returns 401. A key scoped to another node can return 403, while a missing or inaccessible receipt/tenant can return 404. If cancellation authorization cannot be established, the service returns 503. See cancellation usage and responses.

Obtaining your API key

  1. Sign in to the Interlocute dashboard
  2. Navigate to Settings ? API Keys
  3. Click Create Key and give it a descriptive name
  4. Copy the key — it is shown only once
Treat API keys like passwords. Never commit them to source control, include them in client-side code (unless using a publishable key), or share them in plain text.

Recommended local setup

Store your API key in an environment variable rather than hardcoding it: 

# macOS / Linux
export INTERLOCUTE_API_KEY=your_key_here

# Windows PowerShell
$env:INTERLOCUTE_API_KEY = "your_key_here"

Then reference it in your code: 

// C#
var key = Environment.GetEnvironmentVariable("INTERLOCUTE_API_KEY");

// JavaScript
const key = process.env.INTERLOCUTE_API_KEY;
For production deployments, use your platform's secrets management — Azure Key Vault, AWS Secrets Manager, or equivalent. Never store keys in appsettings.json or .env files that are checked into source control.

Key types

Interlocute supports two types of API keys:

Secret keys

Full-access keys for server-side use. These can manage nodes, read logs, and perform all operations. Never expose these in client-side code.

Publishable keys

Restricted keys designed for client-side embedding. Scoped to specific domains via allowlists and limited to chat interactions. Safe to include in front-end code.

Key rotation

To rotate a key, create a new key, update your integrations to use it, then delete the old key. Both keys will work simultaneously during the transition. There is no downtime during rotation.

Scoping & least privilege

When creating keys, assign only the permissions your integration needs. If an integration only sends chat messages, create a key scoped to chat operations. This limits the blast radius if a key is compromised.

Next steps

QuickstartChit-Chat