Setting Up an API Integration and Obtaining a Token
Every request to the Capitan API is authenticated with a token that belongs to a staff user. Rather than reusing a real person's login, create a dedicated API Integration user for each integration: it cannot log in to the Staff Site, it carries only the permissions the integration needs, and it can be retired on its own when the integration is switched off.
Capitan's API documentation describes the available endpoints, filtering, and pagination. Use it once you have a token.
Who can do this: creating staff users and revealing an API token both require the Is Organization Admin? permission. If the Show API Token button reports a permission error, ask an admin at your organization to complete these steps.
Creating the API Integration user
- In the Staff Site, open Admin, then Staff User Admin, and click Add Staff User.
- Set User Type to API Integration. The form drops the email, password, and PIN fields a regular staff user has and instead asks only for a Name.
- Enter a Name that identifies the integration, for example "Website occupancy counter" or "Door access system".
- Tick only the permissions the integration needs, using the table below. Leave everything else unchecked.
- Click Save.
The User Type is locked after saving: an existing staff user cannot be converted into an API Integration user, and an API Integration user cannot be turned back into a staff user. Create a new user instead.
Permissions
| Permission | What it grants |
|---|---|
| Can Manage Events? | Event Setup data: event types, scheduled events, and bookings. |
| Can Manage Customers? | Customer profiles. Ticking it also reveals Can Manage Customer Proficiencies?, which allows editing the proficiencies on a profile. |
| Can Access Reports? | Reporting data, the same information as the Staff Site's Reporting section. |
| Has Griptonite Access? | The access a Griptonite integration requires: customer data plus the ability to configure webhooks. |
| Can Look Up Members By Barcode? | The Look Up Members By Barcode endpoint only, for integrations that need to verify a member and nothing else. |
| Is Organization Admin? | Organization administration, including creating and editing staff users. An integration rarely needs this. |
Example: a door access system that only needs to confirm whether the person scanning a card is a current member gets Can Look Up Members By Barcode? and nothing else. A Griptonite connection gets Has Griptonite Access? and nothing else.
Obtaining the token
Skip the "Obtaining a token" section of the API documentation: it describes exchanging a username and password at the /get-token/ endpoint, which an API Integration user cannot do because it has no password. Use the token shown in the Staff Site instead.
- Open the user from the Staff User Admin list.
- Click Show API Token. The token appears on the page.
- Copy it into the integration's configuration. Each request sends it in the
Authorizationheader, prefixed with the word "Token" and a space, as described under Authenticating a request in the API documentation:
Authorization: Token <token-string>
The token never changes: clicking Show API Token displays the same token every time, so treat it like a password. Anyone holding it has every permission the user has.
Cutting off an integration: from the Staff User Admin list, open the user's menu and choose Retire. The token stops working immediately. Restore on the same menu brings the user, and the same token, back.