engineeradmin
Authentication
Bearer-token lifecycle and credential safety.
Reviewed 2026-08-13Product 1.1
VertexY uses JWT bearer tokens for REST APIs and an HMAC signing secret only for POST /events/ingest.
Token lifecycle
Sign in
bash
curl -X POST "$VERTEXY_API_BASE_URL/auth/login" \
-H "Content-Type: application/json" \
-d '{
"companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
"email": "fraud-admin@acme.com",
"password": "Sup3rSecurePass!"
}'The response contains accessToken, refreshToken, subscription state, plan features, permissions, and assigned access context.
Authorize requests
plaintext
Authorization: Bearer <accessToken>Access tokens default to 15 minutes. Refresh tokens default to 7 days.
Refresh and log out
bash
curl -X POST "$VERTEXY_API_BASE_URL/auth/refresh" \
-H "Authorization: Bearer $VERTEXY_REFRESH_TOKEN"
curl -X POST "$VERTEXY_API_BASE_URL/auth/logout" \
-H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN"Credential safety
- Keep refresh tokens and signing secrets in a server-side secret store.
- Prefer an HTTP-only cookie session when a browser needs authenticated state.
- Never put secrets in browser/mobile bundles, local storage, URLs, or logs.
- Use TLS and rotate any exposed credential.
Event signing secret
Check or rotate the secret with an authenticated admin token:
bash
curl -X POST "$VERTEXY_API_BASE_URL/auth/webhook-secret/status" \
-H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN"
curl -X POST "$VERTEXY_API_BASE_URL/auth/webhook-secret/regenerate" \
-H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN"Rotation invalidates the old signing secret immediately. Update every sender before resuming ingestion.
See Signing and Reliability for request construction and Errors and Status Codes for authentication failures.