Authenticate with the API

Every API request is authenticated with a bearer token. This page walks you from zero to your first successful request, then covers getting tokens through the API itself and revoking them.

Replace https://kollek.example.com in the examples with the address of your instance. The API lives under /api on that address.

The quickest path: create a key in the app

The easiest way to get a token is to create an API key from your profile.

curl https://kollek.example.com/api/me \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

If you get back a JSON document describing your user, you are authenticated. Creating and revoking keys, and seeing when each was last used, is covered in Manage API keys.

Getting a token through the API

You can also authenticate entirely over HTTP, which suits scripts and integrations that manage their own credentials.

Log in with your email and password to receive a token:

curl -X POST https://kollek.example.com/api/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password",
    "device_name": "Reporting script"
  }'

The response contains your token under data.token. The optional device_name names the token so you can recognize it later in your key list.

Two things to know:

• If two factor authentication is enabled on your user, the login endpoint also requires a code field containing a current TOTP code from your authenticator app, or one of your recovery codes.
• Registering through the API works too: POST /api/register creates a user with its own account and returns a token, exactly like signing up in the browser.

Both endpoints are limited to 6 requests per minute, which is plenty for real sign ins and stops brute force attempts.

Revoking tokens

You have two options:

• DELETE /api/logout revokes the token that made the request. Use this when a script finishes with a temporary token.
• The API keys page in your profile lists every token and can revoke any of them. The API keys endpoints in the generated reference do the same over HTTP.

KolleK emails you when a key is created or deleted from the app, so unexpected key activity does not go unnoticed. See Login and security alert emails.

Where to next

• Learn the request conventions in Rate limits and conventions.
• Manage your tokens in Manage API keys.
• Explore every endpoint in the generated reference at /docs/api.