TidyHQ API keys: a guide for your club's tech volunteer

Most clubs have one. The registrar’s partner who works in IT, or the junior coach who studies computer science, who once wrote a little script that pulls the member list out of TidyHQ every Monday and drops it into the coaches’ spreadsheet. It has run quietly for two seasons. Nobody else knows how it works.

If that script signs in with a TidyHQ email and password, this post is for the person who wrote it. Two things changed at the end of 2025. The API’s password grant now takes an API key instead of an account password. And the developer documentation was rebuilt so you can try any call against your own organisation’s data without leaving the page.

Why did TidyHQ stop accepting passwords in the API?

Because the standard moved. The OAuth 2.1 draft deprecates both the password grant and the implicit grant, and sending a person’s real account password from a script was always a weak spot. If the script leaked, the password went with it, and that password also opened the TidyHQ admin dashboard.

An API key is a separate credential that does one job. You can see when it was last used, and you can delete it without touching anyone’s sign-in. That is also useful now that TidyHQ sign-in itself is moving towards passkeys and email codes, where there may be no password for a script to use at all.

Will my existing script break?

Probably not straight away. When the change went in, anyone who had been using the password grant was given a legacy API key that matches their account password at the time. So a script that sends the old password keeps working for now.

There is a catch. Legacy keys are revoked automatically if that person changes their account password. That is exactly the kind of thing that happens quietly at handover time, which is how a Monday report stops arriving and nobody knows why. Swap to a proper key now, while you remember.

How to set it up

1. Go to the TidyHQ developer portal at dev.tidyhq.com and sign in.
2. Open the API Keys tab.
3. Click Add API Key, give it a label you will understand in a year (“Coaches spreadsheet sync”), and click Create API Key.
4. Copy the key straight away with the Copy button. It is shown once and never again.
5. In your script’s token request to https://accounts.tidyhq.com/oauth/token, keep grant_type=password, your client_id, client_secret, your organisation’s domain_prefix and your email as username, and put the API key in password.
6. Once the new key works, delete the legacy key (it has a yellow Legacy badge).

The API Keys list shows when each key was created and when it was last used, which is handy when you inherit a set of keys from somebody and want to know which ones are actually doing anything. The authentication guide has the full request format.

A key belongs to the person who made it, and it acts as that person. If you create it on your own account, the script can see what you can see in the club, no more. When you step off the committee, your keys should go with you, so hand the script over to someone who will create their own.

What about the implicit grant?

It still works, and there is no removal date yet. But if you have a small web app that uses it, plan to move to the authorisation code flow. It is the better practice anyway, and it is the flow the docs lead with.

Can I test API calls without writing code first?

Yes. The rebuilt docs at docs.tidyhq.com let you sign in to your organisation and run calls against each endpoint using your own data, from inside the documentation. Want to see what “list contacts” or “list memberships” actually returns for your club before you build anything? Sign in, pick the endpoint, run it.

Each call comes with sample code in 20 programming languages (34 sets in all), so whatever your volunteer writes in, there is something to copy and adapt. The docs cover both API versions. Use v2 where it has what you need, and fall back to v1 where it does not.

Before you build anything

A couple of honest notes. The API works on your real club data, including when you test from the docs, so try write calls (creating contacts, updating invoices) on something you do not mind cleaning up afterwards.

And check whether you need code at all. Plenty of what club scripts do (syncing payments to accounting, for example) is already covered by the Xero integration and other connections. The developer tools page gives an overview of what is available, and API changes are listed in the changelog.