Rekey

Guide

When to use organizations, and how

An organization groups end-users into a team that shares one subscription. If a company buys your product for twelve people, the company is the customer and those twelve are members of it. If your product is bought by individuals who happen to work somewhere, you do not need this and turning it on will only add a concept your users have to think about.

The decision, in one question

Ask who the invoice belongs to. If the answer is a company, and adding a colleague should not mean a second subscription, use organizations. If the answer is a person, do not.

Two consequences follow from that choice, and they are the reason the feature exists rather than being a label on a group of users. Entitlements resolve to the organization instead of the individual, so a feature the company paid for is available to every member. And credits come out of one shared pool, so usage by any member draws down the same balance.

You can turn it on later

The setting is per Application, under Authentication → Methods. Existing users are unaffected until they belong to an organization, so this is not a migration. Starting without it and adding it when your first company customer appears is a reasonable order to do things in.

What an organization actually is

A named group inside one Application, with members who each hold a role. The roles are fixed and there are three of them: OWNER manages the organization and its members, ADMIN manages members, and MEMBER is read-only. They govern what a member can do to the organization itself, not what they can do in your product. Your own permissions stay yours.

The Rekey operator panel showing an organization called Northwind Trading with one member, a role selector set to OWNER, a pending invitations section, and a billing section with a shared credit pool.
An organization in the panel: members and roles, pending invitations, and the shared billing pool underneath.

Note the billing block at the bottom of that screen. A subscription can name an organization as its beneficiary, and when it does, the credits and feature flags land in the organization pool rather than on the person who paid. That is the whole mechanism. Everything else is membership bookkeeping.

Creating one

There are two directions, and which you use depends on whether teams are self-serve in your product.

Your users create their own. This is the common case for self-serve products. The end-user is authenticated, so the call is made with their token.

From your app, as the signed-in user

const org = await rekey.organizations.create(userToken, {
  name: "Northwind Trading",
  slug: "northwind",
});

await rekey.organizations.invite(userToken, org.id, {
  email: "[email protected]",
  role: "MEMBER",
});

The invited person accepts through your app, which calls POST /api/v1/auth/organizations/accept-invitation with the token from the invitation email. They do not need an account first; accepting creates one if necessary.

You create it for them. This is the case for a sales led deal, where you set the account up before anyone signs in. Do it from the panel, on the Organizations tab, or from your backend with a secret key.

The Organizations tab of an Application in the Rekey operator panel, explaining that organizations group end-users into companies or teams and offering a New organization button.
The Organizations tab. Operators can provision and curate; end-users can create their own from your app.

Pointing billing at the organization

A subscription bills the organization when checkout carries an organizationId. From then on the resolver treats the organization as the beneficiary: every member sees the features the plan grants, and credit spend by any member reduces one shared balance.

One thing to know before you price this

Where two subscriptions grant the same numeric entitlement, the higher value wins. They are not added together. So selling “ten seats” as ten copies of a one-seat plan will not work; sell a ten-seat plan instead. This is deliberate, because taking the maximum keeps an upgrade sane while both subscriptions briefly overlap.

When to skip it

If your product is per-user and always will be, organizations add a layer with nothing in it. If you only need to know which company someone belongs to for reporting, a field on the user is simpler and honest. And if what you actually want is your own staff sharing access to the Rekey panel, that is a workspace member, not an organization. Organizations are for your customers. Workspace members are for your colleagues.

Related: using one Application to sign users in to another, and the docs index for the API reference.

When to use organizations, and how | Rekey