Skip to main content

Authentication

Genvoris exposes two distinct auth surfaces. Use the right one for the right caller.

1. Store API key (server-to-server)​

Used by your backend to manage plans, customers, and mint sessions. Never ship this key to the browser.

Authorization: Bearer gvk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Issued in the Genvoris portal under Integration → API keys.
  • Hashed with SHA-256 server-side; we never see the plaintext after issuance.
  • Optionally domain-restricted (only the widget side honours this).
  • Rotate any time — old keys can be deactivated independently.

If the key is missing, malformed, deactivated, or the underlying account is suspended:

{ "error": "unauthorized" | "invalid_key" | "account_inactive" }

2. Session JWT (browser-side)​

Used by widget code in the end-customer's browser. Minted by you server-to-server, then passed to the page:

POST /api/v1/customers/{id}/sessions
Authorization: Bearer $GENVORIS_API_KEY

{ "expires_in": 900 }       # optional — default 900s, max 3600s

Returned as a signed RS256 JWT:

header.payload.signature

with these claims:

ClaimValue
subend-customer id (ec_…)
sidyour store user id
pidplan id at mint time
isshttps://genvoris.org
audgenvoris-widget
iat / expunix seconds
jtiunique token id

Verifying tokens yourself​

The public key is published as a JWKS document, cached for 1 hour:

GET https://genvoris.org/.well-known/jwks.json

Useful for plugin code paths that want to introspect a token without hitting our API.

TLS​

All endpoints are HTTPS-only. Plain HTTP requests are redirected.