How to connect to Holded

Connecting Holded takes one credential. You create an API token in your own Holded account, choose what that token is allowed to do, and paste it into Apideck Vault. There is no authorisation screen and nothing to approve on Holded's side.

The one decision worth making before you start is what the integration must be able to do, because a Holded token's permissions are chosen when the token is created, module by module.

Prerequisites

• A Holded account on a paid plan. Holded's API is available on all paid plans and not on the Free plan. On the Free plan the Developers section does not appear at all, so there is nothing to create the token from.
• A user who can reach Settings > Developers in that account.
• A view on what the integration needs. Reading records and writing them are separate permissions on the token, set per module.

Create your API token in Holded

1. Sign in to Holded and open your account menu in the upper left, then click Settings.
2. In the Developers section, click Credentials.
3. Click Add API Token.
4. Give the token a name in the description field. Name it after the integration it serves, for example Apideck, so you can recognise it later in the list and revoke the right one.
5. Choose the token's permissions. For each module you can grant read, write or full access. A Holded API token does not inherit the permissions of the user who created it: whatever you select here is exactly what the token can do, for everyone who holds it.
   • Grant read on the modules whose records you want Apideck to retrieve.
   • Grant write or full on the modules where the integration creates or updates records, such as invoices, bills or contacts. With read access only, those calls are refused by Holded even though the connection itself is healthy.
   • When in doubt, start narrow. You can create more than one token if you need to.
6. Click Create Token, then copy the alphanumeric code it generates.

Holded's own walkthrough of these steps is How to generate and use the Holded API.

Treat the token as an account credential rather than a personal one. It is not tied to the person who created it, and anyone holding it reaches everything the account exposes within the permissions you selected.

Connect in Apideck Vault

1. Open Vault and select Holded.
2. Paste the token into the API key field.
3. Save the connection.

Apideck checks the credential against Holded when you save. A valid token leaves the connection ready to use, and Apideck stores it encrypted from that point on. If the check fails, the connection stays unauthorised.

Connection settings

Setting	Required	Description
API key	Yes	The API token you created under Settings > Developers > Credentials. Handled as a sensitive value.

Notes

• Holded is available in both the Accounting and HRIS APIs. The same token backs a connection in either, but each unified API is connected separately. Employee records are reachable through the HRIS connection only.

Revoking access

• To stop Apideck using Holded, delete the connection in Vault. Apideck stops calling Holded and discards the stored credential.
• To invalidate the token itself, remove it in Holded from the same Settings > Developers > Credentials screen where you created it. Holded's help article covers creating tokens but not removing them, so if you cannot find the control, ask Holded support. Any other tool using that token stops working at the same moment.
• To rotate the credential without downtime, create the replacement token first, save it in Vault, and only then remove the old one.

Troubleshooting

There is no Developers section in Settings. The account is on the Free plan, which has no API access, or your user cannot reach that section. Check the plan first, then ask an account administrator for access.

Saving the connection fails straight away. The token was most likely copied incompletely, so create a fresh one and paste it again. Also confirm the token still exists on the Credentials screen and that you copied it from the right Holded account, including whether it came from the demo account rather than the live one.

Reads work, but creating or updating records is refused. The token's permissions for that module are read only. Permissions are set when a token is created, so create a new token with write or full access on the modules the integration writes to, then paste it into Vault in place of the old one.

Requests start failing with HTTP 429. Holded applies two limits at once, a short-term burst limit and a monthly call allowance, both counted per account and shared by every token on it. A burst of 429s that clears by itself is the per-minute limit, and retrying after a short pause is enough. On most plans, persistent 429s mean the monthly allowance is spent and retrying will not help until the allowance resets. Reduce how often the integration syncs, check whether another tool is spending the same allowance, or move to a Holded plan with a larger one. The figures for each plan are on Holded's API limits page and in this connector's Overview.

Employees do not appear. Employee records come through the HRIS connection. The Accounting connection deliberately excludes them, so connect Holded in the HRIS API as well if you need them.

Still stuck? Contact Apideck Support.