API Tokens

API tokens are bearer credentials that let scripts, integrations, and third-party tools call the Geekonomics API on behalf of a user. They're the right tool when you want automated access — a custom integration, a scheduled export, a script that posts daily journal entries — without sharing a real username and password.

Creating a Token

Go to Settings → API Tokens (admin only) and click + New Token. Fill in:

• Name. A human label so you know what each token is for later. "Heroku export job", "Zapier integration", "Nightly P&L script".
• Role. The token inherits this role for authorization purposes. Pick the narrowest role that lets the integration do its job — usually bookkeeper or viewer.
• Expiration. Optional. Set a date if the token shouldn't outlive a specific project.

Click Create. Geekonomics displays the raw token exactly once, in the format gko_<48 hex chars>. Copy it immediately to your secret store, password manager, or environment variable. Once you close the dialog, it's gone — only a bcrypt hash is kept server-side, so neither you nor an admin can retrieve it later. If you lose it, revoke and create a new one.

Using a Token

Send the token in the Authorization header on any API request:

Authorization: Bearer gko_<your token>

The token is recognized at every authenticated endpoint that accepts session cookies. The session context — userId, companyId, role — is stamped from the token's owner so the request scopes to the right tenant automatically.

Tracking and Revoking

The token list on the settings page shows the name, the prefix (gko_xxxx…), the role, when it was created, when it expires, and when it was last used. The last_used_at stamp is updated every time the token authenticates — useful for spotting tokens that nothing's actively using.

Click Revoke on any row to invalidate the token immediately. The revoked timestamp is recorded; the row stays in the list as an audit record. You can also delete revoked tokens once you no longer need the history.

What's next

User Management — for full-fat user accounts when bearer tokens aren't the right fit.