Authentication
API keys
Company administrators create API keys in the portal under Administration → API keys. Each key belongs to one company, has one or more scopes, an optional expiry date and can be revoked at any time (effective immediately). The portal shows when and from which IP address each key was last used.
ek_live_…: live key, documents are delivered over Peppol and reported to the FTA.ek_test_…: sandbox key, documents are validated only.
The secret is displayed once. einvo stores only its SHA-256 hash, so a lost key cannot be recovered: revoke it and create a new one.
curl https://api.einvo.ae/api/v1/invoices?direction=OUTBOUND -H "Authorization: Bearer ek_live_..."
# equivalent
curl https://api.einvo.ae/api/v1/invoices?direction=OUTBOUND -H "X-API-Key: ek_live_..."
Scopes
| Scope | Endpoints | Use it for |
|---|---|---|
documents:read | GET /api/v1/invoices/**, /api/v1/inbox/** (incl. acknowledge) | Status of sent documents, receiving documents from Peppol |
documents:write | POST /api/v1/invoices, POST /api/v1/invoices/validate | Submitting PINT AE UBL (or simplified JSON) from your ERP |
billing | /api/v1/billing/** | Customers, products, invoice drafts, issuing, credit notes, payments, quotes |
webhooks | /api/v1/webhooks/** | Registering and testing webhook endpoints |
GET /api/v1/me works with any scope. Everything else (users, API keys, subscription, company settings) is
reachable only from the portal: an API key can never create another key or change its own permissions.
Rotation
- Create a new key with the same scopes.
- Deploy it to your integration.
- Check in the portal that the old key is no longer used, then revoke it.
Keep keys in a secrets manager or environment variables, never in source code or in the browser. Give each system its own key with the smallest set of scopes, and set an expiry for keys used by contractors.
OAuth 2.0 client credentials
Integrations set up by einvo or by a partner can use OAuth clients instead (portal: Administration → API clients). Exchange the client id and secret for a short-lived access token, then send it as a bearer token:
curl -u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials https://auth.einvo.ae/oauth2/token
# {"access_token":"eyJ...","token_type":"Bearer","expires_in":...}
curl https://api.einvo.ae/api/v1/invoices -H "Authorization: Bearer eyJ..."
OAuth clients act with the ERP_CLIENT role (submit and read documents). For the billing and webhooks APIs, and for sandbox mode, use API keys.
Authentication errors
| Status | code | Meaning |
|---|---|---|
| 401 | INVALID_API_KEY | Unknown, revoked or expired key |
| 401 | ACCOUNT_INACTIVE | The company is suspended or closed |
| 403 | INSUFFICIENT_SCOPE | The key lacks the scope of this endpoint |
| 403 | API_KEY_FORBIDDEN | Endpoint not available to API keys (portal only) |
| 403 | VERIFICATION_PENDING | The company has not been verified by einvo yet |