Skip to main content
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

  1. Go to app.timelyai.com.br
  2. Navigate to Settings → API Keys → New key
  3. Give it a name that identifies its use (e.g., crm-integration, n8n-automations)
  4. Select the required scopes (principle of least privilege)
  5. 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.
ScopePermission
agents:readList and view agents
agents:writeCreate, edit, and delete agents
ScopePermission
conversations:readList and read conversations
conversations:writeCreate, update, and close conversations
messages:sendSend messages via agent
chats:manageManage chat threads, including history
ScopePermission
contacts:readList and search contacts
contacts:writeCreate, edit, and delete contacts
custom-fields:manageManage CRM custom fields
ScopePermission
channels:readList connected channels
channels:writeConfigure and disconnect channels
ScopePermission
training:readView the knowledge base
training:writeAdd and remove documents from training
ScopePermission
workspaces:readView workspaces
workspaces:writeCreate and configure workspaces
ScopePermission
webhooks:manageCreate, list, and delete webhook endpoints
followups:manageManage automatic follow-up rules
ScopePermission
appointments:readView appointments
appointments:writeCreate and cancel appointments
ScopePermission
mcp-servers:manageRegister 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

1

Create the new key

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

Update services

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

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

StatusCauseSolution
401 UnauthorizedKey is missing, invalid, or revokedCheck the x-api-key header
403 ForbiddenValid key, but missing the required scopeAdd 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.