Authentication

API tokens

API tokens are bearer credentials tied to a user account (not a single organisation). They grant access to bearer-authenticated routes such as /api/v1/me and /api/v1/accounts.

Tokens are 64-character hex strings. They are shown once at creation and stored only as a hash server-side — HGV Traders cannot recover a lost token.

Obtaining a token

There are two ways to mint a token:

Dashboard (recommended)

Generate a named token from Dashboard → Settings → API Tokens. You can revoke individual tokens without affecting others.

Programmatic exchange

Exchange email and password for a token via POST /api/v1/auth:

POST /api/v1/auth HTTP/1.1
Host: hgvtraders.com
Content-Type: application/json

{
  "email": "dealer@hgvtraders.com",
  "password": "your-password"
}

{
  "data": {
    "token": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
  }
}

This endpoint is rate-limited (8 attempts per 15 minutes per IP and email). Invalid credentials return 401.

Each successful auth call mints a new token. A user may hold at most 10 active tokens; the oldest are pruned automatically when the cap is exceeded.

Using a token

Include the token in the Authorization header on bearer routes:

GET /api/v1/me HTTP/1.1
Host: hgvtraders.com
Authorization: Bearer a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

Public read endpoints (GET /api/v1/jobs, /events, /posts) do not require a token.

Token lifecycle

Expired or revoked tokens are rejected with 401 Unauthorized.

Token scopes

Tokens grant access to all bearer routes available to the issuing user. Scoped tokens will be available in a future release.

Multi-organisation users

Tokens are user-scoped, not org-bound. When calling /api/v1/accounts, users in multiple organisations must pass organisationId. See Accounts.

Rotating tokens

Revoke a token from Settings → API Tokens, then generate a replacement. Old tokens are invalidated immediately on revocation.

Security

• Store tokens in environment variables — never commit them to source control.
• Rotate tokens if you suspect they have been exposed.
• Prefer dashboard-minted named tokens over repeated POST /api/v1/auth calls in production integrations.