Connect your tools with the API
The API lets a third-party application access your organization's data programmatically: membership records, calendars, bookings and billing. You enable it in two clicks and protect it with a key, a list of authorized addresses and usage monitoring.
Finding out whether the API is for you
The API is aimed at a developer, not at an organization manager. It is used to make your account communicate with software you have written or configured: a custom website, an accounting tool, an in-house display screen, a bridge to another system.
For everyday needs — retrieving the list of members, updating subscriptions in bulk, sending figures to the committee — the import, export and report modules do the job without writing a single line of code.
The API is offered as a beta version: the way it works may still change.
Enable the API and retrieve your key
- Go to Administration›Settings›API BETA.
- Turn on Activate the API module then click Save.
- Your API Key is displayed: copy it with the Copy button and pass it on only to the tool you are connecting.
The key is sent in the X-API-Key HTTP header of every request. Calls must be made over HTTPS; no unencrypted request is accepted.
Protect the key
A few good habits are worth reminding the tool or the provider that uses it:
- never place the key in a code repository; store it in a configuration file kept outside the repository, or in a secrets manager;
- restrict the authorized addresses as soon as the tool calls from a fixed server;
- regenerate the key at the slightest doubt — accidental publication, leaked logs, end of a provider's assignment.
The Regenerate button asks for confirmation, then invalidates the old key immediately. Every application that was using it stops working until it receives the new one: warn them before you click.
Restrict access by IP address
Turn on Restriction by IP address: only requests coming from the addresses you list are accepted, up to a maximum of 10 IPv4 addresses. Enter each address then confirm with Add; your current address is shown on screen to help you.
This is the most effective protection, and the most often overlooked: even if it is disclosed, a key restricted to your provider's address remains unusable anywhere else.
Monitor usage
The screen continuously displays what your key consumes:
- Usage this minute and Usage today, each shown against its limit when a limit is configured;
- Usage Statistics: This week, This month, Total and Last request.
Beyond the limits shown, additional requests are temporarily refused. A counter that constantly brushes against its ceiling usually points to a poorly configured tool, one that keeps requesting the same data over and over instead of caching it.
The date of the last request is useful the other way round: a key that is enabled but has not been called for months is a key to disable.
Discover what the API can do
The full documentation, with parameters and call examples, is displayed at the bottom of the module screen. In broad terms:
- Users: this is the only resource that can be modified. You can list, view, create, edit and delete accounts.
- Configuration: subscriptions, profiles, groups and age categories can be read, but can only be configured from the application.
- Booking: calendars, available time slots, bookings and labels can be read.
- Billing: billing accounts, orders and payments can be read.
