GrivaOneAPI

Getting started

Quickstart

Get a token and make your first authenticated call in two requests.

You can make your first authenticated call to the GrivaOne API in two requests: log in to get an access token, then send that token as a bearer credential on any protected endpoint. No SDK or API key is needed — it is plain JSON over HTTPS.

Base URL

Every request in this guide is sent to https://gulfpay-production.up.railway.app/api/v1. All routes live under the /api global prefix and URI version v1.

Step 1 — Log in for an access token

POST /auth/login takes your email and password and returns an access token plus your tenant context. Accounts are provisioned inside the product; there is no public self-signup.

curl · POST /auth/login
curl -X POST https://gulfpay-production.up.railway.app/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "password": "your-password"
  }'

The response carries the token you will use next, and the companies you can act on:

json · 200 OK
{
  "data": {
    "requiresOtp": false,
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 900,
    "refreshToken": "b7c1e2...",
    "companies": [ { "id": "cmp_123", "name": "Acme Trading LLC" } ]
  },
  "meta": { "requestId": "req_...", "timestamp": "2026-09-07T09:00:00.000Z" }
}

The accessToken is a JWT that expires in 15 minutes (expiresIn, in seconds). Use the refreshToken to mint a fresh one without logging in again — see Authentication.

Step 2 — Call an authenticated endpoint

Send the access token in the Authorization header as a bearer credential. Pass X-Company-Id to select the active company when your login returned more than one.

curl · GET /customers
curl https://gulfpay-production.up.railway.app/api/v1/customers \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "X-Company-Id: cmp_123"

That is the whole loop: log in → carry the token → call the API. Every other endpoint follows the same pattern.

Keeping the token out of your history

For scripting, capture the token into an environment variable rather than pasting it on the command line, so it never lands in your shell history:

shell · capture and reuse
# Keep the token out of your shell history in a variable
TOKEN=$(curl -s -X POST https://gulfpay-production.up.railway.app/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@company.com", "password": "your-password" }' \
  | sed -n 's/.*"accessToken":"\([^"]*\)".*/\1/p')

curl https://gulfpay-production.up.railway.app/api/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

Prefer clicking to typing?

Head to the API console to paste a token and run a real request from your browser — no terminal required.

Where to go next