Skip to main content

API Tokens

API tokens let external clients call GeoPulse REST APIs without using a browser session. They are useful for scripts, MCP clients, dashboards, scheduled jobs, and other automation owned by a GeoPulse user.

What an API token can do​

An API token acts as the user who created it:

  • It can call every authenticated endpoint available to that user.
  • If an administrator creates a token for their own account, that token has the administrator's API permissions.
  • It is separate from browser login cookies and does not require CSRF handling.
  • It records usage metadata such as last-used time and last-used IP.

Treat API tokens like passwords. Anyone with the token can use it until it expires or is revoked.

Create a token​

  1. Sign in to GeoPulse.
  2. Open Profile.
  3. In the Personal group, select Security. You can also go straight to /app/profile?tab=security.
  4. Scroll to the API tokens section.
  5. Click Create Token.
  6. Enter a clear name, such as Home dashboard or Nightly export job.
  7. Optionally choose an expiration date.
  8. Click Create.
  9. Copy the token immediately and store it securely.

GeoPulse shows the token secret only once. After closing the creation dialog, the app only shows a short preview, status, expiration, and usage metadata.

Use a token​

Send the token on every API request with X-API-Key:

curl -H "X-API-Key: <your-api-token>" \
  http://localhost:8080/api/v1/users/me

Or use a bearer token header:

curl -H "Authorization: Bearer <your-api-token>" \
  http://localhost:8080/api/v1/users/me

Either request returns the profile of the user who owns the token. The response (abbreviated) looks like:

{
  "userId": "3f6c1d2e-8a4b-4c5d-9e0f-1a2b3c4d5e6f",
  "email": "user@example.com",
  "fullName": "Jane Doe",
  "role": "USER",
  "timezone": "Europe/Kyiv",
  "avatar": "/avatars/avatar3.png",
  "hasPassword": true,
  "demoMode": false,
  "canViewAdmin": false,
  "adminReadOnly": false,
  "uiPreferences": {},
  "timelineDisplay": {}
}

For more requests, such as reading the timeline or importing a GPX file, see API Examples.

Expiration and rotation​

When creating or editing a token, you can set an expiration date. Tokens without an expiration remain valid until they are revoked.

Good practice:

  • Use one token per script, integration, or automation client.
  • Give each token a name that explains where it is used.
  • Set an expiration for temporary work.
  • Rotate long-lived tokens periodically.
  • Revoke tokens immediately when a client is retired or a token may have leaked.

Manage existing tokens​

In Profile > Security > API Tokens, you can:

  • View token name, preview, status, expiration, last-used time, and last-used IP.
  • Edit the token name or expiration.
  • Revoke a token.

Revoking a token takes effect immediately. Any automation using that token will stop authenticating.

Admin visibility​

Administrators can review and revoke user API tokens from the Administration API and admin UI. This is intended for audit, support, and incident response. Administrators cannot recover the full secret after creation; only the original one-time token value can be used by clients.

Troubleshooting​

If an API request returns 401 Unauthorized, check that:

  • The token was copied before the creation dialog was closed.
  • The token is sent in X-API-Key or as Authorization: Bearer <token>.
  • The token has not expired or been revoked.
  • There are no extra spaces or quotes around the token value.

If a request returns 403 Forbidden, the token is valid but the user does not have permission for that endpoint.