by Piensa ITAuthentication
Authenticate every AdapterDian request with a bearer API key, and rotate it before it expires using the expiry headers.
Every request carries your API key in the Authorization header:
Authorization: Bearer <your-api-key>Piensa IT issues one key per consuming service. The key determines three things you never send in the body:
- The tenant you issue for. It is never taken from the request, so one consumer can’t issue on behalf of another.
- The provider environment (sandbox or production).
- The permissions. Issuing, discarding, resending by email and responding to received documents require
invoices:write; queries don’t.
Never send the key to a browser
The key gives access to your whole tenant and can issue tax documents. Call AdapterDian from your backend, never from a web or mobile client. The API reference asks you to paste it only to try operations, and doesn’t store it.
Expiry
Keys expire (at most one year after they are issued). Every authenticated response announces it:
| Header | When | Example |
|---|---|---|
X-Api-Key-Expires-At |
Always | 2027-09-01T00:00:00.000Z |
Warning |
Fewer than 30 days left | 299 - "La API Key vence en 12 dias; rote antes del 2027-09-01" |
Log the Warning header or alert on it: it is the only notice before the key stops working.
Authentication errors
| Status | code |
Meaning |
|---|---|---|
| 401 | UNAUTHORIZED |
Missing Authorization header, or the key is invalid or revoked. |
| 401 | API_KEY_EXPIRED |
The key expired; detail includes the date. Request a new one. |
| 403 | FORBIDDEN |
The key doesn’t have the permission the operation needs. |
Rotating a key
- Ask Piensa IT for a new key.
- Deploy your service with it.
- Ask for the previous key to be revoked.
The adapter only stores a hash of each key: a lost key can’t be recovered, only replaced.