How to connect to Breathe

This guide walks you through connecting a Breathe account to Apideck Vault.

Breathe authenticates with an API key sent in a request header, not with OAuth. There is no login or consent screen to click through: an Admin switches the API on inside Breathe once, copies the key it shows, and pastes that key into Vault. Nothing has to be registered or approved on Breathe's side first.

Prerequisites

• An active Breathe account. API access is part of a Breathe subscription, so there is no separate API product to buy.
• Admin access in Breathe. Only an account Admin can enable the API and read the key, because the key can read sensitive account data. If you are not an Admin, ask one to complete step 1 and pass you the key.

Steps

1. Enable the API in Breathe and copy your key

An Admin does this once per Breathe account:

1. Sign in to Breathe as an account Admin.
2. Go to Configure > Settings > Integrations > API setup.
3. Select Enable API and confirm that you want to allow API access to your account data.
4. Breathe displays your production API key. Copy it and keep it somewhere safe, such as a password manager or a secret store.

Breathe's own walkthrough of this screen, with screenshots, is here: How to enable the Breathe API.

If the API setup page or the Enable API button is not there, the account you are signed in with is not an Admin. That is the only requirement for this step, so an Admin can do it and hand the key over.

2. Enter the key in Apideck Vault

1. Open the Breathe connector in Vault.
2. Paste the key into the API Key field. It is the only field on this connection, and it is required.
3. Save the connection.

Vault verifies the key immediately by making a read against your Breathe account. A valid key returns a verified connection and you can start using the HRIS API right away.

Notes

• The key grants full account access. Breathe does not offer scoped or read-only API keys, so a single key can reach everything the Breathe API exposes for that account, including employee records, salaries and absence data. Nothing needs configuring to make an integration work, but do make sure the account Admin understands what the key covers before handing it over.
• Regenerating the key is how you withdraw access. There is no separate revoke action: to cut off access, an Admin generates a new key on the same API setup page. That invalidates the old key, so any other integration using the same key stops working at the same moment, and the new key must be pasted into every connection that should keep running.
• The key has no documented expiry. It does not rotate on a schedule, which means rotation is something you decide to do (for example when an Admin leaves), rather than something Breathe prompts you for.
• Sandbox and production keys are not interchangeable. Breathe's developer site issues its own sandbox key, which works against isolated test data on a separate host. A sandbox key will not authenticate against a live Breathe account, or the reverse. See developer.breathehr.com if you want to explore the API before touching real data.
• Reading data in bulk takes some pacing. Breathe pages its results at 25 records by default and 100 at most, and returns the total number of matching records in a Total response header so you can tell how many pages are left. Breathe also caps requests per account per minute, so schedule large backfills to spread out rather than run flat out. The current limit is in the Breathe API FAQs.
• Where to ask about the API. Breathe's general help centre does not answer API questions and points them to developer.breathehr.com. For anything about the connection itself, contact Apideck Support.

Troubleshooting

• Authentication fails when saving the connection. Re-copy the key from Configure > Settings > Integrations > API setup: a partial copy or a trailing space is the usual cause. Also check that the API is still enabled on the account, and that nobody has regenerated the key since you received it, which would leave you holding an old one.
• A connection that used to work suddenly stops. The key was almost certainly regenerated in Breathe. Ask an Admin for the current key from the same page and save it into the connection again.
• You cannot find API setup or Enable API. Your Breathe user is not an Admin. Only an Admin can reach that page, so ask an account Admin to enable the API and share the key.
• Requests start returning HTTP 429. You have exceeded Breathe's per-account request limit, which is shared by everything using that account's key, including any other tool you have connected. Reduce request volume or spread bulk reads over a longer window, then retry. The Breathe API FAQs state the current figure.
• Still stuck? Reach out to Apideck Support.