Authentication

The RandaVerify API uses bearer tokens for authentication. You exchange a username + password for a token, then attach that token to every subsequent request.

Endpoints in this flow

Endpoint	Purpose
POST/login	Exchange credentials for a bearer token
POST/change-password	Rotate the password (required on first login)
POST/forgot-password	Trigger a password-reset email
GET/me	Fetch the current user + their org (sanity check the token)

Logging in

POST /login accepts a standard OAuth2 password form payload (application/x-www-form-urlencoded):

curl -X POST https://api.randaverify.com/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=integrator@your-org.com" \
  -d "password=YOUR_PASSWORD"

Successful response:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "require_password_change": false
}

If require_password_change is true you must call /change-password before any verification endpoint will accept your token.

Using the token

Attach it to every subsequent request as a Bearer header:

curl https://api.randaverify.com/me \
  -H "Authorization: Bearer eyJhbGciOi..."

Token lifetime & rotation

• Tokens are signed JWTs that expire after 60 minutes of issuance.
• There is no refresh-token endpoint. When a token expires you log in again to mint a new one.
• Tokens are immediately invalidated when the user’s password is changed or the account is suspended.

Caution

Treat tokens like passwords. Do not commit them to source control, log them, or pass them in URL parameters. Always use the Authorization header.

First-login password change

1. Obtain a one-time password from RandaVerify Operations (delivered by email).

2. Call /login with that one-time password. You receive a token but require_password_change is true.

3. Change the password:

   curl -X POST https://api.randaverify.com/change-password \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "current_password": "ONE_TIME_PASSWORD",
       "new_password": "YOUR_NEW_PASSWORD"
     }'

4. Re-login with the new password. The fresh token’s require_password_change is false and you can call any verification endpoint.

Forgotten password

curl -X POST https://api.randaverify.com/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "integrator@your-org.com"}'

We respond with 200 OK regardless of whether the email is recognised (to avoid leaking account existence). A reset link is sent to the email if it is on file.

Sanity check

curl https://api.randaverify.com/me \
  -H "Authorization: Bearer $TOKEN"

Returns the user and the org they belong to:

{
  "id": 12,
  "username": "integrator",
  "email": "integrator@your-org.com",
  "role": "org_admin,IDENTITY,WALLET",
  "is_active": true,
  "organisation": {
    "id": 7,
    "name": "Your Org",
    "slug": "your-org",
    "tier_name": "Self-Hosted",
    "subscription_status": "active",
    "subscription_expiry": "2027-04-14T00:00:00",
    "lifetime_units_purchased": 23000,
    "lifetime_badge": { "name": "Silver", "threshold": 20000 }
  }
}

Use this as your liveness check — if /me returns 200 with an org payload, you’re ready to verify.