---
title: 'API tokens'
url: 'https://chronoslice.app/docs/using-chronoslice/api-tokens'
markdown: 'https://chronoslice.app/docs/using-chronoslice/api-tokens.md'
date: '2026-11-14'
description: 'An API token lets a script or app act as you without your password. This page shows how to make and revoke tokens, how to call the API with one, and where the OpenAPI document is. Make a token Open Settings, and find API tokens. Type a name, such as Mac menu bar or Nightly export. Name it after wh…'
taxonomy:
  kb_category:
    - 'Using ChronoSlice'
---

[Docs](https://chronoslice.app/docs)

 [Contact support](https://chronoslice.app/help/new) 

Docs menu

# API tokens

Make a token for a script or app, call the HTTP API with it, and find the OpenAPI document.

 Updated Nov 14, 2026 3 min read

An API token lets a script or app act as you without your password. This page shows how to make and revoke tokens, how to call the API with one, and where the OpenAPI document is.

## Make a token

1. Open **Settings**, and find **API tokens**.
2. Type a name, such as `Mac menu bar` or `Nightly export`. Name it after what will use it, so you can revoke tokens one at a time.
3. Press **Create token**.
4. Copy the token now. ChronoSlice won't show it again.

A token starts with `ts_`. The list shows each token's name, when it was created, and when it was last used.

At a shell you can make one for any account:

```sh
sudo -u chronoslice env CHRONOSLICE_DB=sqlite:///var/lib/chronoslice/chronoslice.db \
  chronoslice token create you@example.com --name "Nightly export"
```

It prints the token and nothing else.

## Revoke a token

Press **Revoke** next to it, then confirm. Anything using the token stops working right away. A token that's revoked stays revoked.

## Use a token

Send it in an `Authorization` header:

```sh
curl -H "Authorization: Bearer ts_your_token" https://time.example.com/api/me
```

A token acts as the person who made it, with that person's role. A member's token reaches only their own time, and an owner's token reaches everything an owner can. Anyone with the token can do what you can, so keep it as private as a password.

Your organization's id is in the answer from `/api/me`. Use it in the paths that start with `/api/orgs/{org}`. For example, to start a timer, leave out `end_at`:

```sh
curl -X POST -H "Authorization: Bearer ts_your_token" -H "Content-Type: application/json" \
  https://time.example.com/api/orgs/ORG_ID/time-entries \
  -d '{"description": "Docs example", "start_at": 1790000000}'
```

`start_at` is a Unix time in seconds. To stop the running timer, send a `POST` to `/api/orgs/ORG_ID/time-entries/ENTRY_ID/stop`. List a range of entries with `GET /api/orgs/ORG_ID/time-entries?from=2026-11-01&to=2026-11-30`.

## The OpenAPI document

The API is described by an OpenAPI document. It's at `/api/openapi.json` on your server, and it doesn't need a token:

```sh
curl https://time.example.com/api/openapi.json
```

You can also print it at a shell with `chronoslice openapi`. Use it to generate a client in your language, or to see every route and field.

A few conventions to know:

- Times are Unix seconds, in UTC.
- Money is a whole number of cents, with a currency code beside it.
- Errors come back as JSON with an `error` code and a `message`, such as `{"error": "forbidden", "message": "You don't have permission to do that."}`.

## When the trial has ended

After the trial, reads still work. Changes are refused with the status 402 and the code `read_only`, apart from the few listed in [The trial](https://chronoslice.app/docs/licence-and-updates/the-trial). Adding a user past your edition's limit is refused with the code `user_limit`.

## What uses tokens already

The Mac app signs in with your email and password once, then makes its own token, named `ChronoSlice for Mac` followed by your Mac's name, and keeps it in the Keychain. You'll see it in this list, and signing out of the app revokes it. See [Installing and signing in](https://chronoslice.app/docs/mac-app/installing-and-signing-in).

## Related

- [What ChronoSlice is](https://chronoslice.app/docs/getting-started/what-is-chronoslice)
- [Settings reference](https://chronoslice.app/docs/installing/settings-reference)
- [Command reference](https://chronoslice.app/docs/help/command-reference)

## Still stuck?

Send us a request: it goes to the people who build ChronoSlice, and the reply comes by email. Include your ChronoSlice version (Settings › Licence shows it) and what you tried.

 [Contact support](https://chronoslice.app/help/new?from=%2Fdocs%2Fusing-chronoslice%2Fapi-tokens)[Your requests](https://chronoslice.app/help/tickets)

---

## Navigation

- Parent: [Using ChronoSlice](https://chronoslice.app/docs/using-chronoslice.md)
- Previous: [Support hour blocks](https://chronoslice.app/docs/using-chronoslice/support-hour-blocks.md)
