Getting started

API keys

How machine access works today with bearer JWTs — and what is planned.

Machine access to the GrivaOne API today uses the same bearer JWT that the product uses — there is no separate API-key system yet. This page documents how to authenticate a headless integration with what exists now, and is honest about what is planned.

There is no self-service key issuance yet

The public API does not issue long-lived, self-managed API keys. Any tool or page claiming to mint a “GrivaOne API key” is not part of this platform. Authenticate with the documented login flow below.

How machine access works today

An integration authenticates exactly like a user: call POST /auth/login to obtain an accessToken, then send it as a bearer credential on every request. See Authentication for the full flow, including refresh and two-factor.

http · the credential you send

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Provision a dedicated user for the integration and script the login:

shell · service login

# A headless integration signs in like any user, then reuses the token
# until it expires (15 min) and refreshes as needed. Store credentials in a
# secret manager — never in source control.
TOKEN=$(curl -s -X POST https://gulfpay-production.up.railway.app/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d "{ \"email\": \"$GRIVAONE_EMAIL\", \"password\": \"$GRIVAONE_PASSWORD\" }" \
  | sed -n 's/.*"accessToken":"\([^"]*\)".*/\1/p')

Token characteristics

Property	Value
Type	Signed JWT, sent as `Authorization: Bearer <token>`
Access-token lifetime	15 minutes (`expiresIn`, in seconds)
Refresh-token lifetime	7 days — exchange it at `POST /auth/refresh` for a new access token
Scope	The signing-in user's role and company access — no finer-grained scopes yet
Revocation	Change the password or revoke the session (`DELETE /auth/sessions/:id`)

Handling credentials safely

Store the integration's email/password in a secret manager or environment variables — never in source control or client-side code.
Send tokens only over HTTPS and never place them in URLs or query strings.
Give the integration user the least privilege it needs (role and company access).
Rotate the integration's password periodically; revoke sessions if a token may have leaked.

What's planned

First-class API keys — long-lived, independently revocable credentials with scoped permissions, issued and managed from a developer settings screen — are on the roadmap. When they ship they will be documented here and announced in the changelog. Until then, the bearer-JWT flow above is the supported path.

Nothing you build needs to change later

Both the current flow and future API keys authenticate with the same Authorization: Bearer header. Code that reads the credential from configuration will keep working when key-based credentials arrive.