Authentication

The Invostaq API has two auth mechanisms depending on what you're doing:

What you're doing	Auth to use	Header
Sending invoices, looking up participants	API key (x-api-key)	x-api-key: sk_test_...
Building an integration or automation	API key (x-api-key)	x-api-key: sk_live_...
Accessing dashboard, settings, directory	Bearer JWT	Authorization: Bearer {token}
Admin operations	Bearer JWT (admin email required)	Authorization: Bearer {token}
Webhook callbacks (inbound)	Secret header	X-Arratech-Webhook-Secret: ...

Rule of thumb: If you're building a server-to-server integration, use an API key. If you're building a UI or accessing settings/analytics, use a Bearer token from the Entra ID session.

---

API keys — for integrations

API keys authenticate calls to the Public API: send invoices and look up participants.

Quick reference

curl "https://api.sandbox.invostaq.com/api/participants/lookup?participantId=0196:971501234567" \
  -H "x-api-key: sk_test_dGVzdGtleS0xMjM0NTY3ODkwYWJjZGVm"

Every request to the public API must include your API key in the x-api-key header.

Missing or invalid keys return 401:

{
  "type": "https://invostaq.com/errors/api-key-required",
  "title": "API key required",
  "detail": "Include your API key in the x-api-key header.",
  "status": 401
}

{
  "type": "https://invostaq.com/errors/invalid-api-key",
  "title": "Invalid API key",
  "detail": "The API key provided is invalid, revoked, or malformed.",
  "status": 401
}

---

Key format

Keys are 44-character base64 strings with a prefix:

sk_test_dGVzdGtleS0xMjM0NTY3ODkwYWJjZGVm
└─────┘ └──────────────────────────────────┘
prefix   44-char base64 value

The full key is shown once when generated. Invostaq stores only the hash — the key cannot be retrieved later.

---

Sandbox vs. live keys

Prefix	Peppol network	When to use
sk_test_	TEST	Development, CI, integration testing
sk_live_	PROD	Real invoice delivery to real recipients

Both key types behave identically — same endpoints, same validation, same rate limits. The only difference is which Peppol network your invoices route through.

Rule of thumb: Use sk_test_ everywhere except production. Invoices sent with test keys never reach real recipients.

---

Managing keys

Generate, list, and revoke API keys from the Invostaq dashboard under Settings > API Keys.

• The full key value is shown once on creation — copy it immediately
• The dashboard displays only the last 4 characters for identification
• Revocation is immediate — any in-flight request using a revoked key fails with 401

---

Tenant scoping

Each API key is bound to exactly one tenant. Every request authenticated with that key can only access that tenant's data. There is no cross-tenant access — a key from Tenant A cannot read or write Tenant B's invoices.

---

Rate limits

Method	Limit	Scope
GET	60 requests/min	Per API key
POST	20 requests/min	Per API key

When you exceed the limit:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/problem+json

{
  "type": "https://invostaq.com/errors/rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "detail": "Too many requests. Retry after the period specified in the Retry-After header.",
  "status": 429
}

Read the Retry-After header and wait that many seconds before retrying. See the TypeScript examples for a client with automatic retry handling.

---

Bearer tokens — for dashboard and settings

The Internal API (settings, dashboard, directory, VAT returns) uses Microsoft Entra ID Bearer JWT tokens. These are issued by the Invostaq web app when you sign in.

Getting a Bearer token

The Bearer token is your Entra ID id_token. You can get it from:

1. Browser DevTools: Sign in at app.invostaq.com, open DevTools → Network, click any /api/ request, copy the Authorization: Bearer ... header value
2. Programmatically: Use the Microsoft Authentication Library (MSAL) with the Invostaq app's client_id

curl https://api.invostaq.com/api/dashboard/stats \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1Q..."

What requires Bearer auth

• Dashboard stats and analytics
• Settings (tenant profile, API keys, webhooks, integrations)
• Customer and supplier directory
• VAT returns
• Invoice creation, approval, and management from the UI
• Payment reminders and aging reports

Token lifetime

Tokens expire after 1 hour. If you get a 401 response that doesn't trigger a sign-out, your token has likely expired — re-authenticate to get a fresh one.

---

Security checklist

• Store keys in environment variables or a secrets manager — never in source code or version control
• Use sk_test_ in development and CI — switch to sk_live_ only in production
• Rotate keys regularly — revoke any key that may have been exposed
• One key per environment — dev, staging, and production should each use their own key
• Never log the full key — use the last 4 characters for identification in logs