Authentication

How to authenticate with VertexY, refresh tokens safely, and manage webhook signing secrets.

Authentication methods

VertexY uses:

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

JWT login flow

1. Log in

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

Response:

json
{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "subscriptionStatus": "active",
  "planCode": "growth",
  "planFeatures": [
    "event_explorer",
    "reviews",
    "graph_explorer"
  ]
}

2. Use the access token

plaintext
Authorization: Bearer <accessToken>

3. Refresh the session

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

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

4. Log out

bash
curl -X POST https://api.vertexY.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

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

Rotate the secret

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

Example response:

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

Rotating the webhook secret invalidates the old secret immediately. Update all senders before resuming event ingestion.

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.