How to invite members from another tool

Before you start

Customer integrations require an active Pro plan, and an owner or admin sets them up under Admin, then Settings, then Integrations.

You need a key with the Invitations permission, described on the form as Create, inspect, and revoke expiring invitations. The Invitation workflow preset is built for this case and grants member lookup and expiring invitation management. The preset includes member lookup so the tool can check whether an address already belongs to the community before it sends another invitation. To grant Invitations alone, choose Custom and select only Invitations.

One key connects one external system to one community, because the key is what identifies the community. The course restrictions field on the key does not apply here: restrictions narrow course, enrollment, and completion reads and events only, so an invitation key ignores that field. See Connect another tool to your Locker for creating and storing a key, and Choose API permissions for what every permission covers.

What the connected tool can do

With Invitations granted, the tool can create an invitation for an email address, inspect one, list the invitations that exist, and revoke one. Requests go to https://lockers.social/api/v1 with the key sent as a bearer token, never to a community's custom domain.

Whoever builds the connection works from the contract at /api/openapi.json on lockers.social. There is a Postman collection at /api/lockers-customer-api.postman_collection.json and a Node client example at /api/examples/client.mjs.

Each invitation expires after the number of days the tool sets when it creates it, from 1 to 30. If the tool does not set one, it lasts 7 days.

The acceptance link belongs to one person

Creating an invitation returns a one-time acceptance link for that recipient. Your tool sends it to that address and nowhere else. A shared inbox or a synced field that other staff can read counts as somewhere else.

Acceptance requires a Lockers account verified on the invited email address, so anyone else who opens the link cannot use it to join. Even so, store and send the link with the same care you give the key that created it.

Send the link again or revoke it

If someone loses the email, set resend on the pending invitation. That issues a fresh link and cancels the old one, so the earlier message stops working from that point. Tell the person to open the newest email in the thread, since the earlier link no longer works.

Revoke a pending invitation you no longer want accepted, for example when the person you invited has left the company that prompted it. Your tool can revoke through the same permission that created it. Revoking applies to invitations that are still pending. Once a person has accepted, they are a member. Open them from Admin, then People. Pending invitations appear on the Invitations tab there. Find members and follow up in People covers that record.

Accepting happens in Lockers

The invited person opens the link, signs in to Lockers with a verified account on that email address, and accepts. An integration cannot do that step on their behalf. It cannot create a verified account for someone, and it cannot grant a membership or paid access on its own.

Your tool knows the moment an invitation goes out. The community changes only when the person signs in and accepts, which can be minutes later or never, so count sent invitations and joined members separately in any reporting. If the recipient has never used Lockers, the account gets created during that first sign-in, covered in Sign in to a community.

Watch invitations from your own system

Four webhook events cover the lifecycle: Invitation created, Invitation updated, Invitation accepted, and Invitation revoked. Invitation accepted is the event that tells your system the offer turned into a membership.

These events need the endpoint bound to a named connection. On the Outbound webhooks form, that is the Named API connection (optional for public events) field, and the note reads Invitation and post events require a named connection. Endpoint permissions and courses cannot exceed its grants. Point the endpoint at the same connection that creates the invitations.

Deliveries contain identifiers and small state hints with no member contact data, so the receiving system fetches current details through the API after an event arrives. See Receive webhooks from your Locker for the signing secret, retries, and Send sample.

If invitations stop going out

Every error response includes a request ID, also sent in the X-Request-Id header, and says whether a retry can help. These codes name a cause you can fix from the Integrations page:

• insufficient_scope means the key does not have the Invitations permission. Create a key that does, or move the connection to the Invitation workflow preset.
• expired_key means the key passed the expiry you chose when you created it. Rotate it, as covered in Rotate or revoke an API key.
• issuer_access_revoked means the admin who created the key no longer has admin access in this community. A current admin creates a replacement key.
• plan_unavailable means the Locker no longer has an active Pro plan, so existing keys are inactive.