Authentication

Authentication methods#

VertexY uses:

• JWT Bearer tokens for most REST endpoints
• HMAC-SHA256 signatures for POST /events/ingest

JWT login flow#

1. Log in#

curl -X POST https://api.getvertexy.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "email": "fraud-admin@acme.com",
    "password": "Sup3rSecurePass!"
  }'

Response:

{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "subscriptionStatus": "active",
  "planCode": "growth",
  "planFeatures": ["event_explorer", "reviews", "graph_explorer"],
  "permissions": ["events:assess", "events:view", "feedback:submit"],
  "departmentId": null,
  "departmentName": null,
  "accessRoleId": null,
  "accessRoleName": null
}

2. Use the access token#

Authorization: Bearer <accessToken>

3. Refresh the session#

The backend refresh endpoint expects the refresh token in the Authorization header:

curl -X POST https://api.getvertexy.com/api/auth/refresh \
  -H "Authorization: Bearer $VERTEXY_REFRESH_TOKEN"

4. Log out#

curl -X POST https://api.getvertexy.com/api/auth/logout \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN"

Token lifetimes#

Default lifetimes in the platform configuration are:

1. Access token Default lifetime is 15 minutes. Use it for normal API calls.
2. Refresh token Default lifetime is 7 days. Use it to get new access tokens.

Security guidance#

Recommended#

• Store refresh tokens only in your server-side application or secure backend-for-frontend layer.
• Treat the webhook signing secret like a password.
• Rotate secrets if they are ever exposed.
• Use TLS for all requests.

Avoid#

• Storing refresh tokens in browser localStorage
• Embedding secrets in mobile or frontend bundles
• Passing access tokens in query strings
• Reusing one webhook nonce across multiple requests

Webhook signing secret#

Your webhook signing secret is used only for POST /events/ingest.

Check status#

curl -X POST https://api.getvertexy.com/api/auth/webhook-secret/status \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN"

Rotate the secret#

curl -X POST https://api.getvertexy.com/api/auth/webhook-secret/regenerate \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN"

Example response:

{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "webhookSigningSecret": "whs_live_new_secret_here",
  "secretPrefix": "whs_live_",
  "rotatedAt": "2026-04-07T12:00:00.000Z"
}

Browser integrations#

If you are building a browser-based app:

• do not call the raw login/refresh endpoints directly from public client code unless you control secure token storage
• prefer a backend-for-frontend that stores refresh tokens in httpOnly cookies
• expose only short-lived access state to the browser

Common authentication errors#

1. 400 Invalid request body Typical causes include a missing companyId, malformed email, or too-short password.
2. 401 Unauthorized Credentials are invalid, or the token is expired or malformed.
3. 403 Forbidden The user is authenticated, but the role does not have access.
4. 402 Payment Required The company has no active subscription, or usage exceeded a protected limit.

For a fuller list, see Errors and Status Codes.