Personal access tokens

Create, use, regenerate and revoke the personal access token (PAT) that authenticates your requests to the TimeLog REST API.

A personal access token (PAT) authenticates your requests to the TimeLog REST API. You send it as a bearer token, instead of a username and password.

A token belongs to the TimeLog user who created it. Every request made with it acts as that user and is checked against that user's permissions. See Authentication for how to choose that user.

You manage your tokens at https://login.timelog.com/personaltoken.

Rules to know first

Rule	What it means for you
The token is shown once.	TimeLog does not store the token value. Copy it when it is created. If you lose it, regenerate the token or create a new one.
Up to 5 active tokens per user.	Use one token per integration, and revoke the ones you no longer use.
Expiry: at most two years.	You choose the expiry date when you create the token. It must be in the future and at most two years ahead.
Expiry is in UTC and is exclusive.	A token with expiry date 25 December is valid until 24 December 23:59:59 UTC.
Status is Active or Expired.	The token list shows each token's status and expiry date. An expired token is rejected with `401`.

Create a token

Log in to your TimeLog site, https://app{server-number}.timelog.com/{account}, as the user the integration will act as.

Open the token page

In the same browser, go to https://login.timelog.com/personaltoken. The page Personal access tokens lists your tokens with their status and expiry date.

Start a new token

Click New token.

Name it and set the expiry

In Name, enter a name that says which integration uses the token, for example Payroll export. In Expiry date (UTC), choose a period, or Custom to pick a date.

Save and copy the token

Click Save. The dialog Successful! shows the token once: copy it with the clipboard button and store it in your secret store right away. Then click Close.

Use the token

Send the token in the Authorization header of every request:

Authorization: Bearer <your-token>

Test it with GET /v1/user/me, which returns the user the token acts as and changes nothing.

curl https://app{server-number}.timelog.com/{account}/api/v1/user/me \
  -H "Authorization: Bearer $TIMELOG_TOKEN" \
  -H "Accept: application/json"

import os
import requests

response = requests.get(
    "https://app{server-number}.timelog.com/{account}/api/v1/user/me",
    headers={"Authorization": f"Bearer {os.environ['TIMELOG_TOKEN']}", "Accept": "application/json"},
    timeout=30,
)
response.raise_for_status()
print(response.json()["Properties"])

200 means the token works. 401 means it does not: see Troubleshooting 401 responses.

In Postman

Create a request

Create a new request, for example GET https://app{server-number}.timelog.com/{account}/api/v1/user/me.

Set the authorization

On the Authorization tab, choose the type Bearer Token and paste the token into Token. Postman then sends the Authorization header for you.

Send it

Click Send. Status 200 OK and your own user under Properties mean the token was accepted.

Store the token in a Postman variable, not in the request itself, so it does not end up in collections you share or export. See Tools and SDKs for other API clients.

Regenerate a token

Regenerating gives an existing token a new value, with the same name. Use it when the value was lost, or to rotate it.

Select the token

On the token page, tick the checkbox of the token.

Regenerate

Click Regenerate, then Proceed to confirm.

Copy the new value

Copy the new value, as when you created the token, and update every integration that uses it.

Update the integration straight after regenerating, so it does not keep using the old value.

Revoke a token

Revoke a token you no longer use, and immediately revoke a token you suspect someone else has seen. A revoked token can no longer be used.

Select the token

On the token page, tick the checkbox of the token.

Revoke

Click Revoke, and confirm if you are asked to.

Requests that still use the token are then rejected with 401.

Plan for expiry

A token stops working on its expiry date, and the integration then gets 401 on every call. To avoid an outage:

Record each token's expiry date where your team will see it, for example in the integration's runbook or a calendar reminder.
Before the date, regenerate the token or create a new one, and update the integration.
Treat a sudden 401 on an integration that used to work as a likely expired or revoked token.

See Security hygiene for how to store and handle tokens.

Was this page helpful?