xingen

Authentication

Every protected endpoint requires a bearer token in the Authorization header. Two token types are accepted — a Firebase ID token, or an xingen API key.

Bearer tokens

Authorization: Bearer xgn_live_your_key_here
  • Firebase ID token — issued when you sign in to the xingen dashboard. Meant for interactive/browser sessions, not long-lived integrations.
  • API key — prefixed xgn_live_ (production) or xgn_test_ (sandbox). Meant for server-to-server and CI/CD integrations.

Creating an API key

Sign up, then go to Settings → API Keys and create a key — this works on the free plan, no upgrade required. The raw key is shown once; store it securely, it can't be retrieved again.

You can also create keys via the API itself:

POST /v1/api-keys
Content-Type: application/json

{
  "name": "Production CI",
  "sandbox": false,
  "quotaLimit": null
}

quotaLimit is optional. On the free plan it's capped at 500 requests/month server-side regardless of what you request — sending null or a higher number is silently clamped to 500. Pro accounts can request a custom limit or leave it null for no cap (fair use applies).

Sandbox vs. live keys

xgn_test_ keys run in sandbox mode:

  • Every request returns a fixed, hardcoded validated result — no real validation is performed, regardless of what you upload. Don't use sandbox results to make business decisions.
  • Sandbox requests never count toward your quota.

xgn_live_ keys run real validation asynchronously and count toward your monthly quota.

What a key can access

xingen doesn't have a scoped-permissions system yet — an API key has the same access as your account: it can submit and read your own invoices and manage your own API keys. There's currently no way to issue a key restricted to a subset of that (e.g. read-only, or validate-only).

Plan-gated validation profiles

EN16931 and PEPPOL are available on every plan. XRECHNUNG, FRANCE, and ITALY require a Pro subscription — upgrading is free and instant from Settings. Requesting one of these from a free account is rejected with 403 Forbidden.

Rotating keys

To rotate without downtime:

  • Create a new key — it's active immediately
  • Update your environment variable / secret manager
  • Revoke the old key once every deployment uses the new value

Both keys work simultaneously during the transition. There is no grace period after revocation — a revoked key stops working on its very next request.

Errors

Missing or invalid credentials return 401 Unauthorized:

{
  "message": "Unauthorized access of protected resource, invalid credentials",
  "error": "UNAUTHORIZED",
  "code": 401,
  "timestamp": "2024-03-01T10:00:00.000+00:00"
}

Exceeding your quota returns 429 Too Many Requests:

{
  "error": "Quota exceeded"
}

See the Error Reference for validation error codes.