Organizations

Written for: ＋ Written for
Deprecated: ＋ Deprecated
Applies to: ＋ Applies to

AdminUpdated Sep 11, 2026

Organizations

Organizations model B2B tenancy: a set of members with roles, optional email-domain auto-join, a security policy, and (for B2B2B) a parent/child hierarchy.

{
  "object": "organization",
  "id": "org_9f…",
  "name": "Acme",
  "slug": "acme",
  "image_url": null,
  "public_metadata": {},
  "max_allowed_memberships": 100,
  "created_by": "user_2a…",
  "created_at": 1757000000000,
  "updated_at": 1757600000000
}

Core endpoints

Method & path	Scope	Notes
`GET /v1/organizations`	`organizations:read`	List, cursor-paginated
`POST /v1/organizations`	`organizations:write`	Create + seat the creator as admin
`GET /v1/organizations/:id`	`organizations:read`	Never includes `private_metadata`
`PATCH /v1/organizations/:id`	`organizations:write`	Update name/slug/image/seat cap/metadata. Emits `organization.updated`. idempotent
`DELETE /v1/organizations/:id`	`organizations:write`	Delete; memberships + invitations cascade. idempotent
`PUT /v1/organizations/:id/metadata`	`organizations:write`	Replace metadata bags wholesale. idempotent
`PATCH /v1/organizations/:id/policy`	`organizations:write`	Set `requireMfa`, `ssoRequired`, `sessionIdleOverrideMs`
`PUT /v1/organizations/:id/parent`	`organizations:write`	Set/clear parent (B2B2B); refuses a cycle
`GET /v1/organizations/:id/hierarchy`	`organizations:read`	Ancestor chain + direct children
`GET /v1/organizations/:id/entitlements`	`organizations:read`	Resolved plan + feature keys

Memberships

Method & path	Scope	Notes
`GET /v1/organizations/:id/memberships`	`organizations:read`	Members with roles
`POST /v1/organizations/:id/memberships`	`organizations:write`	Add an existing user with a role (seat cap enforced). idempotent
`PATCH /v1/organizations/:id/memberships/:userId`	`organizations:write`	Change a role. Demoting the last admin → `LAST_ADMIN`.
`DELETE /v1/organizations/:id/memberships/:userId`	`organizations:write`	Remove a member. Removing the last admin → `LAST_ADMIN`.

Invitations

Method & path	Scope	Notes
`GET /v1/organizations/:id/invitations`	`organizations:read`	Invitations with roles + status
`POST /v1/organizations/:id/invitations`	`organizations:write`	Invite an email to an org (expires in 7 days)
`POST /v1/organizations/:id/invitations/:invitationId/revoke`	`organizations:write`	Revoke a pending invitation

Email domains (auto-join)

Method & path	Scope	Notes
`GET /v1/organizations/:id/domains`	`organizations:read`	Claimed domains + verification state
`POST /v1/organizations/:id/domains`	`organizations:write`	Claim a domain; returns the DNS TXT record to publish. idempotent
`POST /v1/organizations/:id/domains/:domainId/verify`	`organizations:write`	Check the TXT record now, mark verified
`DELETE /v1/organizations/:id/domains/:domainId`	`organizations:write`	Remove a claimed domain

Group → role grants

Directory groups (from SCIM) can be granted an org role; members inherit its permissions (augment-only).

Method & path	Scope
`PUT /v1/organizations/:orgId/groups/:groupId/roles/:roleId`	`organizations:write`
`DELETE /v1/organizations/:orgId/groups/:groupId/roles/:roleId`	`organizations:write`

Examples

curl https://api.atlas.dev/v1/organizations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme","slug":"acme","created_by":"user_2a"}'

const org = await atlas.organizations.create({ name: 'Acme', slug: 'acme', created_by: 'user_2a' });
await atlas.organizations.memberships.add(org.id, { user_id: 'user_zoe', role: 'org:member' });
await atlas.organizations.memberships.update(org.id, 'user_zoe', { role: 'org:admin' });

// Claim a domain for auto-join, then verify after publishing the TXT record
const domain = await atlas.organizations.domains.create(org.id, { domain: 'acme.com', auto_join: true });
console.log(domain.verification); // { record_name, record_type: 'TXT', record_value }
await atlas.organizations.domains.verify(org.id, domain.id);

// Enforce MFA + SSO for the org
await atlas.organizations.updatePolicy(org.id, { requireMfa: true, ssoRequired: true });

Was this page helpful?