API : Authentication
This is the requests that can be made for performing authentication. No other API functions are available without being authenticated.
| Login | Authenticate and get a token that allows access to the rest of the API. |
| Logout | End the current session. |
| Validate token | Check if a token is still valid. |
| Impersonate | Impersonate another user temporarily |
| Reset | Request password reset. |
| Set password | Set password using reset link. |
| Set organization reseller | For organizations. |
| Passkey (WebAuthn) | Overview: relying parties, webauthnOnly and the recovery procedure. |
| Passkey authenticate options | First step of a passkey login. |
| Passkey authenticate | Second step of a passkey login. |
| Passkey register options | First step of adding a passkey to your own account. |
| Passkey register | Second step of adding a passkey to your own account. |
| Passkey credentials | List, rename and delete your own passkeys. |
| Passkey enroll | Recovery: register a passkey using an admin-issued enrollment token. |
How to use a token
The token can be presented in 4 ways:
| Method | Description | Example |
|---|---|---|
| HTTP header | As an HTTP header adhering to the JWT method (preferred) | Authorization: Bearer <TOKEN-STRING> |
| HTTP header | As an HTTP header using API key | X-API-Key: <TOKEN-STRING> |
| Body | As a property in the JSON body on POST requests | { token: <TOKEN-STRING>, other-arg: 'value' } |
| Query | As an argument on the URL | ?a=b&token=<TOKEN-STRING> |
| Cookie | In a cookie, set by the server on login (not recommended due to risk of Cross-Site-Scripting exploitation) | n/a |
A token will only be valid for the number of minutes specified in expiresInMinutes. Before that period has passed, the client application must call any protected page, to keep the token valid, this will reset the timeout (e.g. if expiresInMinutes = 15, then another 15 minutes is available from the time of the request).
Read-only tokens
A persistent token created with scope read (Create token) may only make lookups in search, customers, employees, SIP accounts, mobile accounts, PBX settings, PBX dialplans and call records. Any other request is answered with 403 read_only - also GET requests that change something, such as resetting a password. Path segments must be percent-encoded: a read token is refused for any path with characters outside the RFC 3986 path set (e.g. a raw backslash, space or non-ASCII character). A read token cannot create tokens, and is not accepted by CardDAV, realtime or file downloads. It still acts as its employee: it sees exactly what the employee sees, and the employee's API access filter applies too. Requests made with a read token are marked SCOPE=read in the API log.
Persistent tokens can have an expiry (expires); after it the token is refused with 401 expired. The list of endpoints open to read tokens is kept in src/modules/security/read-scope.ts in tcx-api.