Authentication - Timely.ai

Authentication with the Timely.ai API is done via an API key sent on every request in the x-api-key header. No OAuth, no sessions — just the key.

Sending the key

GET /v1/agents HTTP/1.1
Host: api.timelyai.com.br
x-api-key: tly_live_xxxxxxxxxxxxxxxxxxxxxxxx

For environment variables, always store the key as TIMELY_API_KEY and reference it via process.env (Node), os.environ (Python), or os.Getenv (Go). Never hardcode it.

Creating an API key

Go to app.timelyai.com.br
Navigate to Settings → API Keys → New key
Give it a name that identifies its use (e.g., crm-integration, n8n-automations)
Select the required scopes (principle of least privilege)
Copy the key — it is shown only once

If you lose the key, it cannot be recovered. You will need to revoke it and create a new one. Plan the rollout before revoking keys in production.

Available scopes

Each API key has a set of scopes that define what it can do. Grant only what the service needs.

Agents

Scope	Permission
`agents:read`	List and view agents
`agents:write`	Create, edit, and delete agents

Conversations and messages

Scope	Permission
`conversations:read`	List and read conversations
`conversations:write`	Create, update, and close conversations
`messages:send`	Send messages via agent
`chats:manage`	Manage chat threads, including history

Contacts

Scope	Permission
`contacts:read`	List and search contacts
`contacts:write`	Create, edit, and delete contacts
`custom-fields:manage`	Manage CRM custom fields

Channels

Scope	Permission
`channels:read`	List connected channels
`channels:write`	Configure and disconnect channels

Training

Scope	Permission
`training:read`	View the knowledge base
`training:write`	Add and remove documents from training

Workspaces and team

Scope	Permission
`workspaces:read`	View workspaces
`workspaces:write`	Create and configure workspaces

Automation

Scope	Permission
`webhooks:manage`	Create, list, and delete webhook endpoints
`followups:manage`	Manage automatic follow-up rules

Scheduling

Scope	Permission
`appointments:read`	View appointments
`appointments:write`	Create and cancel appointments

Infrastructure

Scope	Permission
`mcp-servers:manage`	Register and remove external MCP servers

Security best practices

Use one key per service. If a service is compromised, you revoke only its key without affecting everything else. Minimum scopes. A job that only reads conversations does not need agents:write. The smaller the scope, the smaller the blast radius of a leaked key. Periodic rotation. Rotate keys every 90 days or whenever a team member who had access to the credentials leaves. Monitor usage. Under Settings → API Keys, you can see the request volume per key. Unexpected spikes may indicate unauthorized use.

Rotating a key

Create the new key

Under Settings → API Keys → New key, create the replacement with the same scopes as the current key.

Update services

Update the environment variable in all services that use the old key. Deploy or restart the services.

Revoke the old key

After confirming that the services are operational with the new key, click Revoke on the old key. Revocation is immediate — any request with the old key will return 401.

Common authentication errors

Status	Cause	Solution
`401 Unauthorized`	Key is missing, invalid, or revoked	Check the `x-api-key` header
`403 Forbidden`	Valid key, but missing the required scope	Add the missing scope to the key

API keys are isolated by workspace. A key created in the “Support” workspace cannot access data from the “Sales” workspace.

​Sending the key

​Creating an API key

​Available scopes

​Security best practices

​Rotating a key

​Common authentication errors

Sending the key

Creating an API key

Available scopes

Security best practices

Rotating a key

Common authentication errors