Organizations

Pylon ships a complete org, workspace, and team layer in the binary. Users create orgs, invite teammates by email, and change member roles. Users select an active tenant per session, and policies read the active tenant as auth.tenantId. You do not need an external teams service. Apps can customize the org, member, and invite schema. As of v0.3.74, the framework’s /api/auth/orgs/* surface reads and writes through manifest-declared entities (Org, OrgMember, OrgInvite by default; names are configurable). Add logo, industry, billingEmail, plan, or any field you want. The framework reads only the fields it needs and leaves your custom fields alone.

Declaring the entities

Add three entities to your schema. Required fields per entity are listed below. Add any other fields you want.

import { entity, field } from "@pylonsync/sdk";

// REQUIRED fields: id (auto), name, createdBy, createdAt
export const Org = entity("Org", {
  name: field.string(),
  createdBy: field.id("User"),
  createdAt: field.string(),  // ISO 8601

  // Custom fields — your call:
  logo: field.string().optional(),
  industry: field.string().optional(),
  billingEmail: field.string().optional(),
  plan: field.string().optional(),  // "free" | "pro" | "enterprise"
});

// REQUIRED fields: id (auto), orgId, userId, role, joinedAt
export const OrgMember = entity("OrgMember", {
  orgId: field.id("Org"),
  userId: field.id("User"),
  role: field.string(),    // built-in or manifest-declared custom role
  joinedAt: field.string(),

  // Custom fields:
  title: field.string().optional(),
  department: field.string().optional(),
});

// REQUIRED fields: id (auto), orgId, email, role, invitedBy,
// tokenHash, tokenPrefix, createdAt, expiresAt, acceptedAt (optional)
export const OrgInvite = entity("OrgInvite", {
  orgId: field.id("Org"),
  email: field.string(),
  role: field.string(),
  invitedBy: field.id("User"),
  tokenHash: field.string(),
  tokenPrefix: field.string(),
  createdAt: field.string(),
  expiresAt: field.string(),
  acceptedAt: field.string().optional(),
});

Renaming the entities

If your codebase uses Organization instead of Org (or you have a legacy schema), point the framework at your names via the manifest:

import { auth, buildManifest } from "@pylonsync/sdk";

const manifest = buildManifest({
  // ...
  auth: auth({
    org: {
      entity: "Organization",
      memberEntity: "Membership",
      inviteEntity: "Invite",
    },
  }),
});

Disabling the framework’s org surface

Apps that implement org management entirely in their own TypeScript (like older pylon-cloud builds) can opt out of /api/auth/orgs/*:

auth: auth({
  org: { disabled: true },
}),

With disabled: true, the routes return 501 ORG_NOT_CONFIGURED and the framework’s OrgStore is a no-op. Use this when you want full control of the schema and flow.

Roles

Role	Manage members	Delete org	Transfer ownership
Owner	Yes	Yes	Yes
Admin	Yes	No	No
Member	No	No	No

Multiple owners are allowed. The convention is to promote a successor before stepping down. Apps can declare additional least-privilege roles directly in buildManifest:

const manifest = buildManifest({
  // ...
  auth: {
    orgRoles: ["reviewer", "speaker_manager", "billing"],
  },
});

The equivalent helper form is auth: auth({ orgRoles: [...] }). Role slugs must match [a-z][a-z0-9_-]{0,63}. Built-in roles are always available. Do not redeclare them. Custom roles are exact-match labels. They do not inherit member, admin, or any other permission. The framework still reserves member management for owners or admins. Grant application permissions explicitly with auth.hasRole("reviewer") in policies or ctx.requireMember(orgId, { role: ["reviewer"] }) in functions.

Endpoints

All endpoints are under /api/auth/. Org management requires a session. API-key auth is refused with 403 API_KEY_AUTH_FORBIDDEN. A leaked pk.* key cannot create orgs or change member roles.

Endpoint	Method	Role	Purpose
`/orgs`	POST	any session	Create an org; caller becomes Owner
`/orgs`	GET	any session	List orgs the caller belongs to
`/orgs/:id`	GET	any member	Org details + caller’s role
`/orgs/:id`	DELETE	Owner	Delete the org
`/orgs/:id/members`	GET	any member	List members
`/orgs/:id/members/:user_id`	PUT	Owner/Admin	Change role
`/orgs/:id/members/:user_id`	DELETE	Owner/Admin (or self)	Remove member
`/orgs/:id/invites`	POST	Owner/Admin	Send email invite
`/orgs/:id/invites`	GET	Owner/Admin	List pending invites
`/orgs/:id/invites/:invite_id`	DELETE	Owner/Admin	Revoke pending invite
`/invites/:token/accept`	POST	invited user	Accept an invite
`/select-org`	POST	any session	Switch the session’s active tenant

Non-member callers get 404 ORG_NOT_FOUND on /orgs/:id/*. This is by design, so probing cannot enumerate org ids.

Creating an org

curl -X POST https://your-app/api/auth/orgs \
  -H 'Authorization: Bearer pylon_token' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Acme Corp"}'

Response:

{
  "id": "org_a1b2c3...",
  "name": "Acme Corp",
  "created_at": 1735000000,
  "role": "owner"
}

Pylon adds the caller as Owner automatically. created_by is set to the caller’s user id and cannot change.

Listing user’s orgs

curl https://your-app/api/auth/orgs \
  -H 'Authorization: Bearer pylon_token'

Response:

[
  { "id": "org_a1b2", "name": "Acme Corp",  "role": "owner",  "created_at": 1735000000 },
  { "id": "org_c3d4", "name": "Side Hustle","role": "admin",  "created_at": 1735100000 }
]

A user can belong to any number of orgs. Orgs are not exclusive.

Inviting a teammate

curl -X POST https://your-app/api/auth/orgs/org_a1b2/invites \
  -H 'Authorization: Bearer pylon_token' \
  -H 'Content-Type: application/json' \
  -d '{"email": "[email protected]", "role": "member"}'

Response:

{
  "id": "inv_xyz",
  "email": "[email protected]",
  "role": "member",
  "expires_at": 1735604800,
  "accept_url": "https://your-app/api/auth/invites/<token>/accept",
  "token": "<plaintext token, dev mode only>"
}

Pylon sends the email automatically using the configured EMAIL_PROVIDER (or ctx.email). The plaintext token appears in the response only in dev mode. In production, the inviter sees the invite in their dashboard, and the invitee gets the email. Invites are:

Argon2-hashed at rest: a database read cannot extract active invite links.
Single-use: accepted_at is CAS-stamped before the membership is created, so two parallel accepts cannot both succeed.
Email-bound: the accepting user’s account email must match the invite’s email (case-insensitive). Signing in with the wrong account returns 400 WRONG_EMAIL.
7-day TTL: created_at + 7 * 24 * 60 * 60. Expired invites return 400 INVITE_EXPIRED on accept.

Accepting an invite

The invitee signs into Pylon (any method: magic code, password, or OAuth), then makes this request:

curl -X POST https://your-app/api/auth/invites/<token>/accept \
  -H 'Authorization: Bearer pylon_token'

Response:

{ "org_id": "org_a1b2", "role": "member" }

Error cases (all 400 except 401 for unauthenticated):

Code	Meaning
`INVITE_NOT_FOUND`	Token doesn’t match any invite
`INVITE_EXPIRED`	TTL passed
`ALREADY_ACCEPTED`	Token was already burned
`WRONG_EMAIL`	Signed-in account’s email doesn’t match the invite
`ALREADY_MEMBER`	Caller is already a member of the org

Pylon keeps the original invite row (it does not delete it) and stamps accepted_at. This preserves the audit trail.

Managing roles

# Promote a member to admin
curl -X PUT https://your-app/api/auth/orgs/org_a1b2/members/usr_alice \
  -H 'Authorization: Bearer pylon_token' \
  -H 'Content-Type: application/json' \
  -d '{"role": "admin"}'

Guardrails enforced server-side:

Only Owners can promote to Owner. Admins cannot self-promote. 400 BAD_ROLE lists the built-in and manifest-declared roles when a role is unknown. 403 FORBIDDEN is returned when a non-owner tries to promote a member to owner.
The last Owner cannot be demoted. A demotion that would leave zero owners returns 400 LAST_OWNER. Promote someone else to Owner first, then demote.
The last Owner cannot be removed. DELETE /members/:user_id returns the same 400 LAST_OWNER error.

Any member can remove themselves, except a last Owner with no successor.

Active tenant (`auth.tenantId`)

A session can have an active org. The active tenant is what policies, change-event filters, and ctx.auth.tenantId see. The caller’s exact membership role in that org appears consistently in /api/auth/me, SSR PageAuth.roles, policy auth.hasRole(...), and function ctx.auth.roles:

curl -X POST https://your-app/api/auth/select-org \
  -H 'Authorization: Bearer pylon_token' \
  -H 'Content-Type: application/json' \
  -d '{"orgId": "org_a1b2"}'

The server verifies membership before committing. If the caller is not a member of org_a1b2, it returns 403 NOT_A_MEMBER. Clients cannot impersonate an org they do not belong to. Pass null to leave the org (drop back to the “no active tenant” state):

curl -X POST https://your-app/api/auth/select-org \
  -H 'Authorization: Bearer pylon_token' \
  -H 'Content-Type: application/json' \
  -d '{"orgId": null}'

tenantId flows through:

Policies: data.orgId == auth.tenantId row-scopes reads and writes.
TenantScopePlugin: stamps tenantId automatically on insert, and rejects non-admin cross-tenant inserts at before_insert.
ctx.auth.tenantId: available in TypeScript functions.
WS and SSE change-event broadcasts: filtered per client by policy.check_entity_read(entity, &client.auth, &row), so subscribers see only events for rows they can read.

See RBAC for the policy-DSL side.

Tenant scoping in your schema

The convention is to add a tenantId field on org-scoped entities and let TenantScopePlugin handle stamping:

import { entity, field } from "@pylonsync/sdk";

export const Document = entity("Document", {
  title: field.string(),
  body:  field.string(),
  tenantId: field.id("Org"),  // auto-stamped from auth.tenantId on insert
});

export const documentPolicy = policy({
  entity: "Document",
  allowRead:   "auth.tenantId == data.tenantId",
  allowInsert: "auth.tenantId == data.tenantId",
  allowUpdate: "auth.tenantId == data.tenantId",
  allowDelete: "auth.tenantId == data.tenantId",
});

A non-admin caller who tries ctx.db.insert("Document", { tenantId: "other-org", ... }) gets 403 CROSS_TENANT_INSERT from the plugin before the row reaches the database.

Per-org SSO

Each org can have its own SSO IdP. See SSO for OIDC and SAML configuration.

Endpoint	Method	Role	Purpose
`/orgs/:id/sso`	GET	any member	Read redacted OIDC SSO config
`/orgs/:id/sso`	PUT	Owner	Configure OIDC SSO
`/orgs/:id/sso`	DELETE	Owner	Remove SSO config
`/orgs/:id/saml`	GET	any member	Read SAML config
`/orgs/:id/saml`	PUT	Owner	Configure SAML
`/orgs/:id/saml`	DELETE	Owner	Remove SAML config

Security guarantees

Membership check on every /orgs/:id/* route: non-members see 404 ORG_NOT_FOUND regardless of role.
API-key auth refused for all org-management routes. Pylon requires a real session.
Invites are Argon2-hashed at rest with single-use CAS on accept.
Email-bound invites: the accepting user’s email must match the invite.
Last-Owner protection: Pylon rejects a demotion or removal that would orphan the org.
Object-level auth on DELETE /orgs/:id/invites/:invite_id: Pylon matches the URL’s org_id against the invite row before revoke, so an admin of org A cannot revoke an invite from org B, even with the id.

Where to go next

Sessions: select-org, multi-tenant session state
RBAC: policies that read auth.tenantId and auth.hasRole(...)
SSO: per-org OIDC and SAML

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Migrate

Organizations

Declaring the entities

Renaming the entities

Disabling the framework’s org surface

Roles

Endpoints

Creating an org

Listing user’s orgs

Inviting a teammate

Accepting an invite

Managing roles

Active tenant (`auth.tenantId`)

Tenant scoping in your schema

Per-org SSO

Security guarantees

Where to go next

​Declaring the entities

​Renaming the entities

​Disabling the framework’s org surface

​Roles

​Endpoints

​Creating an org

​Listing user’s orgs

​Inviting a teammate

​Accepting an invite

​Managing roles

​Active tenant (auth.tenantId)

​Tenant scoping in your schema

​Per-org SSO

​Security guarantees

​Where to go next

Declaring the entities

Renaming the entities

Disabling the framework’s org surface

Roles

Endpoints

Creating an org

Listing user’s orgs

Inviting a teammate

Accepting an invite

Managing roles

Active tenant (`auth.tenantId`)

Tenant scoping in your schema

Per-org SSO

Security guarantees

Where to go next