Skip to content
English - Australia
  • There are no suggestions because the search field is empty.

Set up an API key for your integrations

Request or create an API key to connect your own systems to Breadcrumb. Learn how to request or create a key, connect to the API and keep your key secure.


An API key lets your own systems connect to your Breadcrumb data without anyone logging in. Most companies use it to pull attendance, induction, permit and form reports into payroll, timesheet or BI tools like Power BI, or to keep sites and site hosts in sync with a project or ERP system.

Think of your API key as a password for your company's data. Anyone who has it can read the information your key allows, including workers' personal details such as licences and addresses. This article covers how to get a key, set it up, and keep it safe.


Before you start

  • You need to be a company admin. Only company admins can create or request an API key.
  • Know what the key is for. Work out which data your integration needs (for example, attendance reports only) so the key gets only the access it needs.
  • Have somewhere secure to store it. A password manager or your IT team's secrets vault is ideal. Don't store it in an email, chat message, or shared document.

There are two ways to get an API key. If you can see the API key option in your profile menu on the web, you can create one yourself. If you can't, request one from the Breadcrumb team.


Create an API key on the web

Self-service API keys are being rolled out to companies in stages. If you don't see the option below, skip to Request an API key from Breadcrumb.

  1. Log in to the Breadcrumb web portal.
  2. Click your name in the top-right corner, then select User profile.
  3. Open API Tokens.
  4. Click I understand ➡ Add API Token.
  5. Add a descriptive label to the key under the Name section to indicate its purpose.
  6. Tick only the permissions your integration needs (see Choose the right permissions below).
  7. If the key will create new sites, choose the template site that new sites should be copied from.
  8. Save the key.
  9. Copy the key straight away and store it somewhere secure. The full key is only shown once. After you leave the screen, you'll only see a masked version.

Choose the right permissions

Each key has its own set of permissions, and each part of the API checks for a specific one. Only tick what your integration actually uses. A reporting tool, for example, doesn't need permission to create or remove site hosts.

  • Sites: create and update, deactivate, or list sites.
  • Site hosts: list, add or update, and remove site hosts.
  • Company hosts: list, add or update, and remove company hosts.
  • Workers: pre-register workers on a site.
  • Suppliers: list and add or update suppliers, and add or remove suppliers on sites.
  • Reports: read attendance, induction, competency card, permit, approval, form, SWMS and user directory reports.


Request an API key from Breadcrumb

If self-service isn't switched on for your company yet, our team can create a key for you. Because a key gives access to your workers' personal information, we verify every request before we issue one.

  1. Contact your Customer Success Manager or our support team on 1300 127 323. The request needs to come from your main Breadcrumb contact, or from someone they've referred to us.
  2. Include the following in your request:
    • Company name: exactly as it appears in Breadcrumb.
    • Company host: the name and mobile number of the company admin the key will be linked to.
    • Purpose: what you'll use the key for, for example attendance reporting in Power BI.
    • Access needed: full access, reports only, or specific areas such as sites or suppliers.
  3. We'll confirm the request with you. This may include a call to your main contact or your company's main phone number.
  4. Once verified, we'll email you a secure link to your key. We never put the key itself in an email.
  5. Open the link and copy the key to a secure location before the link expires. The expiry date is in the email.

Note: We only send API keys to our customer, not to integration partners or vendors. If a third party is building the integration for you, you're responsible for sharing the key with them securely.


Connect to the API

Once you have your key, your IT team or integration partner can start using the API.

  1. Open the API documentation for Australia and New Zealand: https://ext-au.1bc.app/swagger/index.html
  2. Add your key to every request in the X-Api-Key header.
  3. Test the connection with the ping endpoint (GET /integration/ping). A successful response means your key is working.

A few things to know:

  • Your key only sees your company. Every request returns your company's data only.
  • One request at a time. Each key processes one request at a time, with up to five more queued. Anything beyond that receives a 429 error, so build in a retry.
  • Reports are paged. Large reports are returned in pages, so your integration needs to request each page in turn.
  • Missing permission. If a request returns a 403 error, the key is missing the permission for that part of the API, or the key isn't valid.


Manage an existing API key

If you created a key on web, you can manage it from the same API Tokens screen. Each admin can see and manage the keys they created.

  • Edit: change the label or permissions.
  • Rotate: generate a new key value. The old value stops working immediately, so update your integration straight away.
  • Revoke: switch the key off permanently.

Every change to a key is recorded in your company's security log. If your key was issued by our team and you need it changed or switched off, contact your Customer Success Manager.


Keep your key secure

  • Store the key in a password manager or secrets vault, never in plain text.
  • Don't email the key or paste it into chats, tickets or shared documents.
  • Only share it with people or partners who need it, and make sure they store it securely too.
  • Use a separate key for each integration so you can switch one off without affecting the others.
  • If you think a key has been exposed, rotate or revoke it straight away, or contact us immediately if our team issued it.

Misuse of an API key can be a reportable data breach, so it's worth treating your key with the same care as your own password.


Need help or have a question?

Contact our Support Team on 1300 744 666 or email support@breadcrumb.co.

We’re happy to help!