Authentication
The API accepts API key authentication, or session cookies (accessToken) when using the web app.
Priority: cookie vs API key
If the request includes a valid session cookie (accessToken), the server uses only that session and does not apply the API key from headers on that same request. To test key-based integration from a browser where you are logged into abaco, use a private window, another profile, or clear API cookies; server-side clients typically have no session cookie, so the API key applies as expected.
Token format
The token must be in the form:
<Key ID>:<Secret>When a key is created, the Secret is generated as base64url (URL-safe, similar to standard base64). For example, if your Key ID is abk_abc123 and your Secret is your_base64url_secret, the full token would be:
abk_abc123:your_base64url_secretThe first : separates Key ID and Secret; secrets generated by abaco do not contain :.
How to send it
Option 1: Authorization header (recommended)
Especially when calling the API from a browser on another origin (CORS): this header is allowed on preflight requests.
Authorization: Bearer abk_abc123:your_base64url_secretOption 2: X-API-Key header
Also allowed from a browser on another origin: the API lists X-API-Key in CORS alongside Authorization.
X-API-Key: abk_abc123:your_base64url_secretExample with curl
Replace YOUR_KEY_ID, YOUR_SECRET and https://api.abaco.hn with your values:
curl -X GET "https://api.abaco.hn/business-partners" \
-H "Authorization: Bearer YOUR_KEY_ID:YOUR_SECRET"Error responses (code in JSON body)
| HTTP | Code | Meaning |
|---|---|---|
| 401 | TOKEN_MISSING | No valid session cookie and no API key in headers. |
| 401 | INVALID_API_KEY | Unknown or revoked Key ID, or wrong Secret. |
| 401 | API_KEY_EXPIRED | The key has an expiration date that has passed. |
| 401 | API_KEY_NO_USER | The key is valid but no company user could be resolved (e.g. no active business proprietor or administrator in the company). |
| 401 | TOKEN_EXPIRED / INVALID_TOKEN / SESSION_EXPIRED | Web session (JWT/cookie) issues, not API key. |
| 403 | WEB_SESSION_REQUIRED | Route is web-session only (not API key), e.g. change company or user permission management. |
| 403 | API_KEY_MANAGEMENT_FORBIDDEN | Key management is not available with integration credentials (API key). Use the web app. |
| 403 | API_KEY_DELETE_FORBIDDEN | API keys cannot perform any DELETE request; use the web app to remove resources. |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests with the same API key in the time window. See Rate limits. |
Responses usually include a Spanish message as well as code.
API keys are not managed through the documented integration flows (neither with an API key nor by scripting the API with a session token): creation and revocation are only in the web app (abaco.hn → Settings > Integrations), for users with the business proprietor or administrator role.
DELETE operations: with an API key, any DELETE request returns 403 with code API_KEY_DELETE_FORBIDDEN. Removing records (products, documents, partners, etc.) must be done from the web app with a signed-in session.
Company scope: when using an API key, every request is tied to the company that owns that key. Do not try to switch company context in the request body or query string; the server derives scope only from the key and blocks access outside that company.
Accounting reports: with an API key, access to accounting report templates does not require the granular accounting.reports.view permission that applies to web users; the key operates within that key's company scope.