API Tokens

• What an API token is
• Before you start
• Where to find API tokens
• Create a token
• The secret is shown only once
• What the token list shows
• Revoke a token
• Using the token

What an API token is

The Klubraum REST API lets your own scripts, your club website or another tool work with the calendar events and the members of your club. Every request identifies itself with a personal access token that you create in the Klubraum app.

Such a token always belongs to a single Klubraum and to the person who created it. It carries only the scopes you pick, it can expire, and you can revoke it at any time. And it can never do more than you can do yourself: on every request, your current permissions in the app are checked as well. If you lose a permission, the token loses it too.

Before you start

• You are an administrator of the Klubraum. Other members do not see this function.
• Your club is on a suitable plan: the member list, invitations and removals are included in Plus, every other endpoint needs Pro. On a plan without API access, a note about upgrading appears when you tap the tile.

Where to find API tokens

Open the Settings and go to Current Klubraum. The second tile there is API tokens, with the subtitle Personal access tokens for the Klubraum API — directly below the tile for changing the name of your club.

Note: The tile right below it is for the token used by membership requests. That is a different token, meant only for the join form on your club website — you can read about it in Join Request on Club Website.

Create a token

Tap the + in the top right of the screen (Create token). The dialog Create API token asks you for three things.

Name

Free text, up to 100 characters, for example “Website sync”. Give every tool its own token and name it after that tool — later you will know exactly which token you may revoke.

Scopes

Here you decide what the token is allowed to do. There are four scopes:

• members:read — read the member list.
• members:write — invite and remove members.
• events:read — read calendar events.
• events:write — create, update, cancel and delete calendar events.

A write scope always covers the matching read scope. As soon as you tick members:write, members:read is ticked along with it and can no longer be unticked, and only the write scope is stored on the token. The same goes for events:write and events:read. At least one scope is required.

Tip: Pick the smallest set of scopes that does the job. A script that only shows your events on your website needs events:read and nothing else.

Expires after

Choose 30, 90, 180 or 365 days — or Never. Never shows a warning, and rightly so: a token without an expiry date stays valid until someone revokes it. Whenever you can, give a token a limited lifetime.

Then tap Create.

The secret is shown only once

Right after creation, the app shows the complete token — the long secret that starts with klubraum_pat_. Copy it with the copy button and store it straight away where your script or tool reads it from, ideally in a password manager or a secrets store.

Important: This is the only moment at which the secret is visible. It cannot be retrieved later, not even by us. If you lose it, revoke the token and create a new one.

Never put the secret somewhere public: not in the JavaScript of your website, not in a public repository, and not in a club conversation. Anyone who has it can use the API with exactly the scopes you gave the token.

What the token list shows

The screen lists all tokens of your Klubraum. For each one you see:

• the name you gave it,
• a short prefix beginning with klubraum_pat_ that identifies the token without revealing the secret,
• the scopes as chips,
• when it was created, when it expires and when it was last used.

The date of last use is a good way of spotting tokens nobody needs any more. Revoked tokens stay in the list and are shown struck through.

Revoke a token

Tap the delete icon on the token (Revoke token) and confirm with Yes, revoke. Revoking takes effect immediately: from that moment on, every request made with this token is rejected. It cannot be undone — a revoked token cannot be reactivated.

Tip: Do you want to replace a token that is still in use? Then first create the new token, switch your script or tool over to it, and only revoke the old one afterwards.

Using the token

Send the token with every request as a bearer token in the Authorization header:

Authorization: Bearer klubraum_pat_…

Which endpoints exist, which parameters they expect and what they return is described in the developer section and in the interactive API reference.