API Tokens and OAuth Clients in Practice

This chapter describes how an integration obtains and uses access to TAS in practice: a static API token, a client-server OAuth client, and an OAuth client whose access is approved by a user. Managing tokens and clients in the administration (creating, revoking, rotating) is covered in the API Access article – here we continue from the perspective of an integrator who already has a token or client and wants to use it.

API token

The simplest option for server-to-server integration. An administrator with the $ApiTokenAdmin role generates the token for you on the API Access screen and hands it over to you (it is displayed only once). You use it in every call:

curl "https://vase-tas.cz/tasks" -H "Authorization: Bearer <api-token>"

The token represents one system user and has exactly that user's permissions – API tokens have no scopes. It is valid for at most 730 days from generation (default validity is 365 days); after that it stops working and a new one must be generated.

One token, one purpose
For each integration, have the administrator create a separate system user with only the permissions the integration needs, and a separate token. Revoking one integration then does not affect the others.

Confidential OAuth client (server-to-server integration)

A confidential client is suitable where access is not requested by a specific user – the integration authenticates directly as a selected system user using the Client ID and Client secret (the client_credentials grant):

curl -X POST "https://vase-tas.cz/oauth/token" \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=client_credentials"
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 28800
}

The access token is sent the same way as an API token, in the Authorization: Bearer <access_token> header. It is typically valid for 8 hours (expires_in in seconds) – after it expires, the integration calls /oauth/token again. For client_credentials, TAS does not issue a refresh token.

The Client ID and Client secret are created and handed over to you by the administrator on the API Access › OAuth Clients screen. Like the token, the Client secret is displayed only once.

Public OAuth client (applications whose access the user approves)

A public client has no Client secret – instead, it uses an authorization code with PKCE, and access is always requested by a specific user. This is how, for example, AI assistants connect to TAS (see the MCP Server article).

  1. The application generates a code_verifier (a random string) and derives a code_challenge from it (SHA-256, base64url).
  2. The application redirects the user to: `` GET /oauth/authorize?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&code_challenge=<challenge>&code_challenge_method=S256&state=<state> ``
  3. TAS redirects the signed-in user to the consent screen (/oauth/consent/...), where they see the application name and the address they will be redirected to after approval, and confirm or deny access.
  4. After approval, TAS redirects back to redirect_uri with the code parameter.
  5. The application exchanges the code for a token: ``bash curl -X POST "https://vase-tas.cz/oauth/token" \ -d "grant_type=authorization_code" \ -d "code=<code>" \ -d "redirect_uri=<redirect_uri>" \ -d "code_verifier=<verifier>" \ -d "client_id=<client_id>" ` The response contains access_token, expires_in and, this time, also refresh_token for renewal without repeated user consent (grant_type=refresh_token`).

The token represents the permissions of the user who granted consent – not a system user. An overview of who has granted access to applications and when it was last used is available in API Access › OAuth Grants; both the user and an administrator with the $ApiTokenAdmin role can revoke access there at any time.

Scopes are not supported
TAS 5.19.12 does not distinguish OAuth access scopes. A token or client always has the full permissions of the user it represents – design the integration based on which user (or system user) you connect to it, not on an assumed scope of permissions.

Rotation and revocation

What you rotateHow
API tokenGenerate a new one in API Access and revoke the old one with the Revoke action. Revocation is immediate and irreversible.
Confidential client's Client secretThe administrator uses the Generate new Client secret action on the client – the old one stops working immediately, so enter the new value in the integration right away.
Public client accessThe user or administrator removes the grant in API Access › OAuth Grants; the application must request consent again.

A detailed description of the screens and roles can be found in the API Access article; secure storage of the Client secret or API key on your integration's side (if it resides in TAS, e.g. in a calculation script) is described in the Vault article.

Rate limiting on authentication endpoints
The /oauth/authorize, /oauth/token, /oauth/revoke endpoints and client registration accept at most 60 requests per minute from a single IP address. When the limit is exceeded, TAS responds with a "too many requests" error – adjust any integration that refreshes tokens too often so that it uses a token until it expires.

Related: API Access, REST API: Authentication and Basic Calls, MCP Server, Vault.

REST API: Authentication and Basic Calls

API Access
Syca (opens in a new tab)

Powered by HelpDocs (opens in a new tab)