How to connect another tool to your Locker

Before you start

Customer integrations require an active Pro plan, and owners or admins of a Pro Locker can manage them. On a Locker without Pro, the page says so directly: Creating and rotating keys requires an active Pro plan. Existing keys are inactive while integrations are unavailable, and you can revoke them at any time.

Plan on one key per system. The key is what tells Lockers which community the request belongs to, and nothing else in the request does that, so two tools sharing a key become impossible to tell apart in your activity and impossible to cut off separately. A community can hold up to ten active keys at once.

Requests go to https://lockers.social/api/v1 with the key sent as a bearer token. That address stays the same even when your community has a custom domain, because API requests are never sent to a custom domain.

Create a key

1. 1

   Open the Integrations page

   Open Admin, then Settings, then Integrations.

2. 2

   Name the connection

   Under Customer API keys, type a Connection name. Name it after the system on the other end, the way the placeholder CRM sync does, so the key still makes sense to you months from now.

3. 3

   Pick a workflow preset

   Pick a Workflow preset: CRM sync, Calendar sync, Invitation workflow, Content drafts, or Custom.

4. 4

   Set the request rate

   Set Requests per minute, anywhere from 1 to 600. The default is 60.

5. 5

   Check the permissions

   Read through Exact permissions. While any preset other than Custom is selected, the boxes are fixed, and the page says Preset permissions are fixed. Choose Custom to change them.

6. 6

   Restrict courses if you need to

   Leave Restrict to course IDs (optional, comma-separated) blank for all courses, or list the courses this connection should cover, in the form the placeholder shows: course-one, course-two. The helper text under it reads Restrictions apply only to course, enrollment, and completion reads/events; other scopes remain independent.

7. 7

   Set an expiry

   Set Expires after (days), from 1 to 90. The default and the longest option are both 90.

8. 8

   Create the key

   Select Create key.

Which preset to choose

Take the preset that matches the job. Custom is for the cases a preset cannot handle: the tool needs a mix no preset offers, or it needs less access than a preset grants. For what each individual permission covers, see Choose API permissions.

• CRM sync grants members, contact data, enrollments, and completions.
• Calendar sync grants published community events only.
• Invitation workflow grants member lookup and expiring invitation management.
• Content drafts reads and writes drafts, and publishing is not included.
• Custom means you choose each permission explicitly.

Store the key before you leave the page

The key appears once, at the moment you create it, and after that only when you rotate it. It starts with cs_live_. Put it straight into a secret manager or an environment variable in the tool you are connecting, and keep it out of source control, URLs, logs, and any code that runs in a browser.

If you lose the key, rotate it to get a new one. The connection keeps its identity through a rotation, so the drafts, invitations, and webhook bindings created through it stay attached to it. See Rotate or revoke an API key.

Confirm the connection works

Under Connection check, select Test the connection. Lockers uses the key the way your tool will and reports back the connection's name, environment, permissions, restrictions, expiry, and quota windows. The same panel shows the Base URL to point the tool at, the Environment, and the Budget the connection draws on.

Do this right after you create a key, and again after every rotation. A missing permission shows up in that panel in a few seconds, rather than in a failed sync a week later.

What can stop a key working

Every request rechecks more than the key. Lockers rereads the admin who created it, the community's status, the plan, the key's expiry and revocation, its permissions, its course restrictions, and its quotas. A change to any of those can stop a key that worked yesterday.

If the admin who created a key stops being an admin, the connection stops with them, because the key never has more authority than the person who issued it. Create keys from an account that will still be an admin next quarter. The full list, and what to do in each case, is in Rotate or revoke an API key.

Files for whoever builds the connection

A developer, or you in a no-code tool, can build the connection from these four files on lockers.social:

• /api/openapi.json is the API contract.
• /api/lockers-customer-api.postman_collection.json is a Postman collection.
• /api/examples/client.mjs is a small Node client example.
• /api/examples/webhook-receiver.mjs is a Node webhook receiver example.