API Tokens and Integration

This chapter is for users integrating scripts or other systems. Ordinary web use does not require an API token.

1. Create and Use Your Token

An API token is a script credential with the same permissions as your account. Protect it like a password.

1. Sign in and open API Token from the user menu at the upper right.
2. Create a token, give it a descriptive name, and choose a validity period from 30 days to one year, or no expiration.
3. Copy and securely store the token immediately. Its full value is displayed only once.
4. Send Authorization: Bearer <API_TOKEN> in script request headers. Do not put tokens in URLs, shared documents, or repositories.
5. Revoke unused tokens to invalidate them immediately.

Limits: Tokens cannot create other tokens or change passwords.

If exposed: Changing a password does not automatically revoke existing tokens. Explicitly revoke the affected token.

2. Revoke Tokens Centrally

Platform administrators can open User Menu → API Token → All Users to inspect names, prefixes, and last-used times, and revoke tokens.

Disable departing employees' accounts to prevent further use of their tokens. Token creation and revocation are audited.

3. View API Documentation and Verify Integration

Open API documentation:

1. API documentation is disabled by default. Operations staff must set TIMECHO_API_DOCS_ENABLED=true in deployment configuration and recreate the service.
2. A platform administrator opens /api/v1/docs under the platform URL.
3. Enter a personal API token under Authorize to inspect and try endpoints.

Access: The OpenAPI description is at /api/v1/openapi. Regular users and database administrators cannot access either documentation entry.

Send a read-only request:

Administrator example; replace the domain and token:

curl -fsS https://agent.example.com/api/v1/system/status \
  -H 'Authorization: Bearer <API_TOKEN>'

Success: The response contains system self-check results with each item's status, severity, and description.

Status	Check first
401	Token completeness, expiration, revocation, and whether the account is disabled
403	Role, mandatory first password change, and endpoint permissions

Further integration: Develop against the API documentation for your platform version. Tokens do not bypass database permissions, budgets, or approvals. Contact the Timecho team for additional support with batch calls, streaming conversations, or other integrations.