Professional API: Organisation keys

One read-only key that covers every professional in your organisation, owned by the firm rather than one person.

Last reviewed

What an organisation key is

A normal professional API key reads only your own practice. An organisation key adds the pro:org:read scope, which widens every read on the TheWILL.ai Professional API to the rows of every seat in your organisation: appointments, clients, matters, invoices, time entries, documents and the rest.

  • It works alongside a read scope and does not grant anything on its own. Give an organisation key “Everything in your practice” (pro:read), or only the areas your reporting needs, such as Billing (pro:billing:read). A key limited to areas reads those areas across every seat, and nothing else.
  • It is read only. An organisation key cannot carry any write scope, so it cannot create wills or change data.

Creating one

Only an active owner or admin of the organisation can create an organisation key. Admins who are suspended or on leave cannot.

  1. Sign in and open the API keys page at /account/developer/keys, then choose Live on the Test / Live switch.
  2. Create a new key and tick Organisation-wide (all seats).
  3. If you are an owner or admin of more than one organisation, choose which organisation the key reads for. The Create key button stays disabled until you do.
  4. Copy the key straight away. It is shown only once.

Screenshot, for illustration only

The Developer page under Account, where API keys and webhook endpoints are created and managedThe Developer page under Account, where API keys and webhook endpoints are created and managed
The Developer page under Account, where API keys and webhook endpoints are created and managedThe Developer page under Account, where API keys and webhook endpoints are created and managed
The Developer overview. Open API keys in the sub-navigation to create a key; the Organisation-wide option appears in the create form only for an organisation owner or admin.

Do not see the option?

The option appears only for people who can create organisation keys, and only while your organisation has API access on its plan.

Call the API with it exactly as you would with a personal key:

# The organisation key reads for every seat in the organisation.
# Keep it in your server's environment, never in a browser or shared file.
curl --retry 5 "https://thewill.ai/api/v1/pro/ext/clients/?page_size=50" \
  --config org.curlrc  # made like api.curlrc, from $ORGANISATION_API_KEY

Limiting it to your firm’s IP addresses

You can limit an organisation key to the addresses your servers call from. Enter them in Allowed IP addresses when you create the key, or later with Edit IP addresses in the key’s ⋯ menu. Leave it empty to allow any address.

  • Enter single IPv4 or IPv6 addresses, or ranges in CIDR form such as 203.0.113.0/24.
  • A request from any other address is refused with 403 and the code ip_not_allowed, and the organisation’s owners and admins get an email, at most once a day for each key.
  • Rotating the key keeps its list.
  • Only organisation keys can carry a list. Personal and test keys do not offer the field.

When people leave

The key belongs to the organisation, not to the person who created it. It keeps working if its creator leaves the firm or stops being an admin, so an integration does not break because of a staff change.

It stops working if the organisation is dissolved, suspended, terminated, merged or has ceased trading, or loses API access on its plan.

Keeping it safe

An organisation key can read client data across the whole firm, so treat it like a master password.

  • Any active owner or admin of the organisation can see and revoke its keys.
  • Revoke a key at once if you think it has been exposed, then create a new one.
  • Keep it on a server, never in a browser, a mobile app or a shared document.

Can’t find what you’re looking for?

Our support team is here to help. Contact us and we’ll get back to you as soon as possible.

Contact us

We use cookies to improve your experience. See our Cookie policy (opens in a new tab) for details.