Creating & managing SwiftFox API keys

API keys let you connect external tools to your account through the SwiftFox API. A key authenticates requests to the API so an outside system can read data from — and write data to — your SwiftFox environment. You create and manage keys from Settings → Integrations → API keys.

Access to this page is controlled by permissions: you need access to Settings (the Admin permission) to see it. If you cannot find the page, ask your system administrator.

Open the API keys page

1. Open Settings from the main menu.
2. In the left-hand settings menu, go to the Integrations group and select API keys.
3. The API keys landing page opens, showing the keys already set up for your account.

The API keys landing page

A table lists your existing keys with these columns:

• Key name — the recognisable name given to the key.
• Expiry — the date the key stops working.
• User — the user whose access the key inherits (shown prefixed with "API:").
• Circle — the circle the key is limited to (Global if it is not restricted).
• Scope — what the key is allowed to do, for example Full: Read & Write, or a summary of the custom feature access. The table scrolls sideways if the Scope column is off-screen.

Above the table on the right are two tabs — Active and Disabled — so you can switch between keys that are in use and keys that have been switched off. A toolbar above the table gives you Search, Sort, a pin control, and a show/hide control for columns.

Create an API key

1. Select Create API key at the top right. A panel opens from the right.
2. Key name — give the key a recognisable name so you can tell later what it is used for (for example, the service and environment it connects).
3. Expiry date — choose how long the key stays valid: 90 days, 6 months, 1 year (the default), or Custom date to pick your own. Annual rotation is recommended.
4. Scope (optional) — choose what the key can do. It defaults to Full access. Select Custom to limit it: choose a Feature (Records — people, organisations and their related data — Forms, Events, or Financial) and an Access level (Read to retrieve data only, or Read & Write to also create and update data). Select + Add scope to add more feature-and-access-level rules.
5. Assigned user (optional) — the key inherits this user's access permissions, so anything using the key can only reach the data that user could see in SwiftFox. It defaults to System.
6. Assigned circle (optional) — restrict the key to a specific circle if your account uses circles. It defaults to Global (no restriction).
7. Select Create key.

What a key can actually reach is the combination of its scope, the assigned user's permissions and the assigned circle — whichever is most restrictive wins.

Copy your key straight away

After you create the key, SwiftFox shows the key value once, with the warning: Copy your API key now. You will not be able to see it again after closing this drawer. Select Copy key and store it somewhere secure before you close the panel. If you lose the value, you cannot retrieve it — you will need to rotate the key (or create a new one) to get fresh credentials.

Manage an existing key

Select the three-dot menu at the end of a key's row for these actions:

• Rotate key — generate new credentials for the key while keeping its settings. Use this when a key may have been exposed, or on a regular rotation schedule.
• Clone key — create a new key that copies the settings of the existing one, so you don't have to re-enter the scope, user, and circle.
• Disable key — switch the key off. You are asked to confirm, because the key becomes immediately invalid for all API requests. Disabled keys move to the Disabled tab.

Related

The API keys page sits under Settings → Integrations, alongside the Xero and XPM integrations. For an overview of everything in Settings, see the System/Settings — Overview guide.