Docs/API/Authentication

Authentication

How to obtain and use an API token. Requests are authenticated with a JSON Web Token (JWT) sent in the Authorization header.

Obtaining a token

Get a token by logging in with an email account. The token is returned in the token field.

POST /api/user/login Public
bash
curl -X POST https://api.geometry-labs.com/api/user/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}'

# Response
# {
#   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "user": { "id": "...", "email": "...", "plan": "pro", ... }
# }

You can also register a new account with POST /api/user/register, which returns a token in the same shape.

Using the token

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

http
Authorization: Bearer <your-token>

Token expiry & revocation

  • Expiry: tokens are valid for 7 days.
  • Revocation: changing your password or resetting it invalidates all previously issued tokens (via a tokenVersion check).
  • Plan claim: the token embeds your plan. If your plan changes, obtain a fresh token to pick up the new plan.

Social login

Discord and Google OAuth are available via GET /api/auth/discord and GET /api/auth/google. These are browser redirect flows: the user is sent back to the app with a token in the URL. They are intended for the web UI, not server-side API clients.

API keys

For server integrations, use a dedicated API key instead of a 7-day login token. API keys are available on Pro and Team plans, do not expire by default, and can be revoked independently of your password.

Creating a key

Sign in on the API account page to create, list, and revoke keys. The full secret is shown exactly once, when it is created.

To manage keys from a script, use the same endpoints the account page uses (auth required):

MethodPathDescription
GET/api/v1/user/api-keysList your active keys (no secrets).
POST/api/v1/user/api-keysCreate a key. Returns the secret once.
DELETE/api/v1/user/api-keys/:idRevoke a key.

Using a key

Send the key as a bearer token, or via the X-API-Key header:

http
Authorization: Bearer gl_your_api_key
# or
X-API-Key: gl_your_api_key
  • Keys are stored hashed; the secret can never be read back.
  • Maximum of 10 active keys per account.
  • Never embed a secret key in browser or mobile code.

Important notes

Server-to-server only

The API enforces a CORS allowlist in production. Browser applications served from other origins cannot call the API directly. Use server-side calls and keep your token secret.