Organizations

Organizations add multi-tenancy to your IdP: users belong to one or more organizations, can switch their active organization, and receive per-org claims (org_id, org_slug, org_role) in every token. The feature is capability-probed: AuthKit activates it automatically when the three required tables are present in the database — no config flag needed unless you want to tune the defaults.

Database schemaCopy Anchor Link

Created automatically. With schema auto-management on (the default), AuthKit creates the three organization tables on boot — nothing to do. If you disabled it (schema: { autoManage: false }), call ensureAuthkitSchema(this.db) in a migration, or create the tables yourself. For reference, the column names the Lucid store expects:

// auth_organizations
schema.createTable('auth_organizations', (table) => {
  table.string('id').primary()
  table.string('name').notNullable()
  table.string('slug').notNullable().unique()
  table.string('logo_url').nullable()
  table.json('metadata').nullable()
  table.timestamps(true, true)
})

// auth_organization_members
schema.createTable('auth_organization_members', (table) => {
  table.string('id').primary()
  table.string('organization_id').notNullable()
    .references('id').inTable('auth_organizations').onDelete('CASCADE')
  table.string('account_id').notNullable()
  table.string('role').notNullable().defaultTo('member')
  table.timestamps(true, true)
  table.unique(['organization_id', 'account_id'])
})

// auth_organization_invitations
schema.createTable('auth_organization_invitations', (table) => {
  table.string('id').primary()
  table.string('organization_id').notNullable()
    .references('id').inTable('auth_organizations').onDelete('CASCADE')
  table.string('email').notNullable()
  table.string('role').notNullable().defaultTo('member')
  table.string('token_hash').notNullable().unique()
  table.string('invited_by').notNullable()  // accountId of the inviter
  table.timestamp('expires_at').notNullable()
  table.timestamp('accepted_at').nullable()
  table.timestamps(true, true)
})

ConfigurationCopy Anchor Link

Configure organizations in defineConfig:

defineConfig({
  // …
  organizations: {
    // enabled: true,        // default: auto (on when tables exist)
    claimStrategy: 'active', // emit claims from the session's active org (default)
    allowSelfCreate: true,   // signed-in users may create their own org
    roles: ['owner', 'admin', 'analyst'],
    invitationTtlHours: 72,
  },
})

The effective policy is resolved org setting → global setting → config.organizations → library default, and the member-facing /account/orgs screens, the admin console and the Admin API all read it. Declaring organizations in defineConfig locks the organizations_policy setting (see Config locks), so the policy fields above are the policy; leave organizations out of the config to manage the policy from the console instead.

Without the config key, the policy lives in the organizations_policy runtime setting — see Runtime Settings:

node ace authkit:settings:set organizations_policy \
  '{"allowSelfCreate":false,"invitationTtlHours":72,"roles":["owner","admin","member"]}'

Lucid store modelsCopy Anchor Link

The three organization tables are owned by the library — ensureAuthkitSchema creates and evolves them — so you don't write models for them. The built-in models are used by default: just build the store and the OrganizationsCapability is there.

import { lucidAccountStore } from '@adonis-agora/authkit-server'

accountStore: lucidAccountStore(AuthUser, {
  // …your existing options (mfaIssuer, password, …)…
})

organizationModels: true is the explicit spelling of that same default. To turn the capability off — for example because you relied on supportsOrganizations === false — pass organizationModels: false.

If your auth tables live in their own connection or schema (static connection = 'auth'), pass the three model classes explicitly — the built-in models don't declare a connection:

import { lucidAccountStore } from '@adonis-agora/authkit-server'
import AuthOrganization from '#models/auth_organization'
import AuthOrganizationMember from '#models/auth_organization_member'
import AuthOrganizationInvitation from '#models/auth_organization_invitation'

accountStore: lucidAccountStore(AuthUser, {
  // …your existing options (mfaIssuer, password, …)…
  organizationModels: {
    OrgModel: AuthOrganization,
    MemberModel: AuthOrganizationMember,
    InvitationModel: AuthOrganizationInvitation,
  },
})

The store returns an OrganizationsCapability that the host kit uses automatically. The /account/orgs screen is mounted by default; without this capability it would answer 403, which is exactly what used to happen when the host forgot organizationModels.

Token claimsCopy Anchor Link

When a user has an active organization (set via the signed cookie from /account/orgs), these claims are added to every id_token, userinfo response, and JWT access token:

Claims follow the store, not the consentCopy Anchor Link

The active org is captured on the Grant at consent time and every refresh re-emits it — for as long as the refresh token lives (30 days by default). That capture is only a snapshot, so at every mint (code exchange, refresh, userinfo) AuthKit checks it against the account store before emitting anything:

• the account must still be a member of the org (getOrgMembership);
• the org must still exist (findOrgById);
• org_role is the member's current role and org_slug the org's current slug — never the values captured at consent.

If the check fails, the token is still issued, just without org_*. resolveTokenRoles receives the verified activeOrg (or null). A store without findOrgById and getOrgMembership (the OrganizationsCapability, or a partial one) has nothing to check against, so it never emits org claims.

A store error is not swallowed: the token request fails rather than silently dropping the org or re-emitting the stale one.

Removing a member revokes access immediatelyCopy Anchor Link

Checking at mint time only takes effect at the next refresh. So when a membership ends, AuthKit also revokes the grants that carry that org for that account — their access and refresh tokens included — and records a per-sub revocation so cookie-based clients drop the session on their next request. This happens on every removal path:

Grants for other orgs, or without an org, are left alone. The relying party sees invalid_grant on the next refresh and sends the user back through /authorize; the new grant comes out without the org. Revocation is best-effort: if it fails (for example, the adapter is down) the membership change still succeeds, the failure is logged at error, and the mint-time check drops the claim on the next refresh. Adapters that cannot enumerate grants (no list) rely on the mint-time check alone.

To revoke by hand, use AdminSessionsService#revokeOrgGrants(orgId, accountId?).

A role change does not revoke anything: the next refresh simply carries the new role.

Consuming the tenant in a relying partyCopy Anchor Link

On the client side (@adonis-agora/authkit-client) the org claims are promoted to first-class fields on the resolved Identity — you do not have to reach into identity.raw:

const identity = await ctx.auth.getIdentity()
identity.orgId    // 'org-9'  | null
identity.orgSlug  // 'acme'   | null
identity.orgRole  // 'owner'  | null

The derivation also accepts the tenant claims other IdPs emit (active_organization_id, organization_id, tenant_id, tid), so an app behind a third-party IdP (see BYO IdP) reads the same field. active_organization_id wins when several are present.

That same value is published to @adonis-agora/context as tenantId, which is what lets @adonis-agora/authz scope roles and queries per tenant automatically:

import { tenantFromContext } from '@adonis-agora/authz'

defineConfig({ resolveTenant: tenantFromContext })

Requiring an active organizationCopy Anchor Link

Authenticated is not the same as inside a tenant. A logged-in user with no active org reaches your controller with an undefined tenant — and a tenant-scoped authz check then falls back to the global scope, which is the worst place to land by accident. The requireOrg middleware closes that:

export const middleware = router.named({
  auth: () => import('@adonis-agora/authkit-client/auth_middleware'),
  requireOrg: () => import('@adonis-agora/authkit-client/require_org_middleware'),
})

// Web: redirects to the org picker (default `/account/orgs`).
router.group(() => { /* … */ }).use([middleware.auth(), middleware.requireOrg()])

// API: 403 `no_active_organization` instead of a redirect.
router.group(() => { /* … */ }).use([middleware.auth(), middleware.requireOrg({ mode: 'api' })])

// Restrict to a known set of tenants.
router.get('/internal', [C, 'x']).use(middleware.requireOrg({ oneOf: ['org-9'] }))

It is fail-closed: no session, or no active org, means no pass.

Account console — /account/orgsCopy Anchor Link

Every authenticated user has access to /account/orgs:

Every one of those writes has a JSON mirror under /account/api/orgs/* — same guards, same effective policy, JSON errors instead of a redirect — for hosts that render their own organization screens. Role changes, which the console only offers through the admin path, are there too. See Host-owned account screens.

Invitation flowCopy Anchor Link

Invitations are sent by email (mail.onOrgInvitation) and carry a short-lived signed token (SHA-256 hash stored in the DB, TTL from organizations_policy.invitationTtlHours). The accept URLs are:

GET  /account/orgs/invitations/:token/accept   → accept form (no session required)
POST /account/orgs/invitations/:token/accept   → accept the invitation

The token is validated against the hash, TTL, and the authenticated account's email before creating the membership.

Customize the invitation emailCopy Anchor Link

Wiring mail.onOrgInvitation is optional. Without it the host kit sends the invitation itself through the host's default @adonisjs/mail mailer, branded and translated like every other AuthKit email. Provide the hook only to take the message over:

mail: {
  onOrgInvitation: async ({ email, orgName, orgSlug, role, acceptUrl }) => {
    await mailer.send((m) =>
      m.from(env.get('EMAIL_FROM')).to(email)
        .subject(`You have been invited to ${orgName}`)
        .text(`Accept your invitation as ${role}: ${acceptUrl}`)
    )
  },
}

Reacting to organization eventsCopy Anchor Link

Every organization operation is audited, and each audit event carries orgId as a first-class field. Wire events.onEvent (or a webhook) to keep your own tables in sync without depending on any other Agora library — see Events → Provisioning your own database:

events: {
  onEvent: async (event) => {
    if (event.type === 'organization.created') {
      await Company.create({ authOrgId: event.orgId! })
    }
  },
}

If you do use @adonis-agora/authz, its event-driven provisioning subscribes to the same events off the diagnostics bus and can assign tenant-scoped roles directly:

await defineAuthzProvisioning({
  store,
  on: {
    'organization.created': (event, store) =>
      store.assignRole({ type: 'user', id: event.accountId! }, 'org:owner', {
        tenantId: event.orgId!,
      }),
  },
})

Read event.orgId from the top level. The diagnostics bus strips metadata (it may contain PII), so event.metadata.orgId is undefined on that path.

Governance invariantsCopy Anchor Link

• An organization always has at least one owner. Removing or demoting the last owner is rejected with last_owner.
• LGPD cascade: deleting an account removes all its memberships and pending invitations. The org itself is not deleted (the other members still exist).
• Data export includes the user's memberships and pending invitations (see Compliance).

Admin console — /admin/orgsCopy Anchor Link

When the admin console is enabled, an Organizations section appears under /admin/orgs:

Admin REST APICopy Anchor Link

All organization operations are available under /api/authkit/v1/organizations. Requires the Admin REST API to be enabled and a Bearer API key.

# Create an organization
curl -X POST https://idp.example.com/api/authkit/v1/organizations \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp", "slug": "acme", "ownerAccountId": "acc-42" }'

# Invite a member
curl -X POST https://idp.example.com/api/authkit/v1/organizations/org-1/invitations \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@acme.com", "role": "admin" }'

Backend SDKCopy Anchor Link

const authkit = await createAuthkit({ mode: 'remote', baseUrl, apiKey })

// List
const { data: orgs } = await authkit.organizations.list()

// Create
const org = await authkit.organizations.create({
  name: 'Acme Corp',
  slug: 'acme',
  ownerAccountId: 'acc-42',
})

// Detail (includes members + pending invitations)
const detail = await authkit.organizations.get(org.id)
detail.members     // AuthkitOrgMember[]
detail.pendingInvitations  // AuthkitOrgInvitation[]

// Members
await authkit.organizations.members.add(org.id, { accountId: 'acc-7', role: 'member' })
await authkit.organizations.members.updateRole(org.id, 'acc-7', 'admin')
await authkit.organizations.members.remove(org.id, 'acc-7')

// Invitations
const inv = await authkit.organizations.invitations.create(org.id, {
  email: 'bob@acme.com',
  role: 'member',
})
await authkit.organizations.invitations.revoke(org.id, inv.id)

// Delete
await authkit.organizations.delete(org.id)

See SDK for the full type table.

ReactCopy Anchor Link

@adonis-agora/authkit-react ships four hooks and two pre-built components for organizations. They fetch data from the JSON endpoints the host kit exposes (/account/orgs/json, /account/orgs/invitations/json, /account/orgs/:id/json) and POST mutations via the standard account routes.

HooksCopy Anchor Link

import {
  useOrganizations,
  useOrganization,
  useSwitchOrganization,
  useOrgInvitations,
} from '@adonis-agora/authkit-react'

// List the current user's organizations + pending inbound invitations
const orgs = useOrganizations()
// orgs.data: OrgEntry[]   (id, name, slug, logoUrl, role, isActive)
// orgs.invitations: OrgInvitationEntry[]
// orgs.loading, orgs.error
// orgs.actions.create({ name, slug }), orgs.actions.leave(orgId), orgs.actions.accept(token)

// Detail of one organization (members + active invitations)
const org = useOrganization(orgId)
// org.data: ActiveOrgDetail   (includes members: OrgMemberEntry[])
// org.actions.invite({ email, role }), org.actions.removeMember(accountId), org.actions.revokeInvitation(invId)

// Switch the active organization
const switcher = useSwitchOrganization()
// switcher.activate(orgId), switcher.deactivate()
// switcher.loading

// Pending invitations for the current user
const invitations = useOrgInvitations()
// invitations.data: OrgInvitationEntry[]
// invitations.actions.accept(token), invitations.actions.refetch()

ComponentsCopy Anchor Link

import {
  OrganizationSwitcher,
  OrganizationProfile,
} from '@adonis-agora/authkit-react'

// Dropdown to switch the active organization; optionally shows a "Create org" button
<OrganizationSwitcher
  allowCreate={false}  // default; set true when the organizations_policy.allowSelfCreate setting is on
  createLabel="New organization"
  className="my-custom-class"
/>

// Full management card: members, invitations, leave/invite controls
<OrganizationProfile
  orgId={activeOrgId}
  className="my-custom-class"
/>

Both components use the same --authkit-* CSS variables as the rest of the component kit. See React Components for the theming reference.

Audit eventsCopy Anchor Link

Every organization operation emits an audit event: