Organization API Endpoints

REST API reference for all organization and roles endpoints. Proxy endpoints are called with a user JWT; admin and roles endpoints require your project API key.

Proxy endpoints

End-user facing endpoints. Authenticate with the user's JWT returned by AuthGate after sign-in.

Authorization: Bearer <user_jwt>

All operations are scoped to the authenticated user — users can only manage organizations they belong to, and only within the limits of their role's permissions.

Organizations

MethodPathDescription
POST/api/proxy/orgsCreate an organization
GET/api/proxy/orgsList orgs the current user belongs to
GET/api/proxy/orgs/:orgIdOrSlugGet a single org
PATCH/api/proxy/orgs/:orgIdOrSlugUpdate org name or slug
DELETE/api/proxy/orgs/:orgIdOrSlugDelete org (admin only)

POST /api/proxy/orgs

Request body

{
  "name": "Acme Corp",
  "slug": "acme-corp"
}

Response 201

{
  "org": {
    "id": "org_abc123",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

The calling user is automatically added as a member with the default admin role.

GET /api/proxy/orgs

Response 200

{
  "organizations": [
    {
      "org": {
        "id": "org_abc123",
        "name": "Acme Corp",
        "slug": "acme-corp",
        "created_at": "2025-01-15T10:00:00Z",
        "updated_at": "2025-01-15T10:00:00Z"
      },
      "membership": {
        "id": "mem_xyz",
        "role": {
          "key": "admin",
          "name": "Admin",
          "permissions": ["*"]
        },
        "joined_at": "2025-01-15T10:00:00Z"
      }
    }
  ]
}

PATCH /api/proxy/orgs/:orgIdOrSlug

Requires org:manage permission.

Request body

{
  "name": "Acme Corporation",
  "slug": "acme-corporation"
}

Members

MethodPathDescription
GET/api/proxy/orgs/:orgIdOrSlug/membersList members
PATCH/api/proxy/orgs/:orgIdOrSlug/members/:idUpdate member role
DELETE/api/proxy/orgs/:orgIdOrSlug/members/:idRemove member

GET /api/proxy/orgs/:orgIdOrSlug/members

Response 200

{
  "members": [
    {
      "user_id": "user_abc",
      "name": "Alice",
      "email": "alice@example.com",
      "picture": "https://example.com/alice.jpg",
      "membership": {
        "id": "mem_xyz",
        "role": {
          "key": "admin",
          "name": "Admin",
          "permissions": ["*"]
        },
        "joined_at": "2025-01-15T10:00:00Z"
      }
    }
  ]
}

PATCH /api/proxy/orgs/:orgIdOrSlug/members/:id

Requires org:manage permission. :id is the user_id of the member.

Request body

{
  "roleKey": "editor"
}

Invitations

MethodPathDescription
POST/api/proxy/orgs/:orgIdOrSlug/invitationsSend an invitation
GET/api/proxy/orgs/:orgIdOrSlug/invitationsList pending invitations
DELETE/api/proxy/orgs/:orgIdOrSlug/invitations/:idRevoke an invitation
POST/api/proxy/orgs/invitations/acceptAccept an invitation

Sending, listing, and revoking invitations requires org:manage permission. Accepting an invitation requires only a valid token.

POST /api/proxy/orgs/:orgIdOrSlug/invitations

Request body

{
  "email": "alice@example.com",
  "roleKey": "member"
}

Response 201

{
  "invitation": {
    "id": "inv_abc123",
    "email": "alice@example.com",
    "role": { "key": "member", "name": "Member" },
    "expires_at": "2025-01-22T10:00:00Z",
    "created_at": "2025-01-15T10:00:00Z"
  }
}

POST /api/proxy/orgs/invitations/accept

The calling user must be authenticated. The token is included in the invitation email link.

Request body

{
  "token": "inv_accept_token_from_email"
}

Response 200

{
  "membership": {
    "id": "mem_new",
    "org_id": "org_abc123",
    "user_id": "user_xyz",
    "role": { "key": "member", "name": "Member", "permissions": ["documents:read"] },
    "joined_at": "2025-01-16T09:00:00Z"
  }
}

Returns 400 if the token is expired or already used.

Leave org

POST /api/proxy/orgs/:orgIdOrSlug/leave

The authenticated user removes themselves from the organization.

Response 200

{
  "success": true
}

Returns 400 if the user is the last admin of the organization.

Admin endpoints

Server-to-server endpoints using your project API key. Use these for programmatic management from your backend — not from client-side code.

Authorization: Bearer <api_key>

Organizations

MethodPathDescription
GET/api/v1/orgsList all organizations in the project
POST/api/v1/orgsCreate an organization
GET/api/v1/orgs/:orgIdGet an organization by ID
PATCH/api/v1/orgs/:orgIdUpdate an organization
DELETE/api/v1/orgs/:orgIdDelete an organization

GET /api/v1/orgs

Response 200

{
  "orgs": [
    {
      "id": "org_abc123",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "member_count": 5,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 1
}

POST /api/v1/orgs

Request body

{
  "name": "Acme Corp",
  "slug": "acme-corp"
}

No user is automatically added as a member — use the members endpoints to add initial members.

Members (admin)

MethodPathDescription
GET/api/v1/orgs/:orgId/membersList all members of an org
POST/api/v1/orgs/:orgId/membersAdd a user to an org
PATCH/api/v1/orgs/:orgId/members/:memberIdUpdate a member's role
DELETE/api/v1/orgs/:orgId/members/:memberIdRemove a member

POST /api/v1/orgs/:orgId/members

Request body

{
  "userId": "user_xyz",
  "roleKey": "editor"
}

Response 201

{
  "membership": {
    "id": "mem_new",
    "org_id": "org_abc123",
    "user_id": "user_xyz",
    "role": {
      "key": "editor",
      "name": "Editor",
      "permissions": ["documents:read", "documents:write"]
    },
    "joined_at": "2025-01-16T09:00:00Z"
  }
}

PATCH /api/v1/orgs/:orgId/members/:memberId

:memberId is the user_id of the member.

Request body

{
  "roleKey": "admin"
}

List user's organizations

MethodPathDescription
GET/api/v1/users/:userId/orgsList all orgs a user belongs to

Response 200

{
  "organizations": [
    {
      "org": {
        "id": "org_abc123",
        "name": "Acme Corp",
        "slug": "acme-corp"
      },
      "membership": {
        "id": "mem_xyz",
        "role": { "key": "admin", "name": "Admin", "permissions": ["*"] },
        "joined_at": "2025-01-15T10:00:00Z"
      }
    }
  ]
}

Roles endpoints

Manage project-level role definitions. All endpoints require your project API key.

Authorization: Bearer <api_key>
MethodPathDescription
GET/api/v1/rolesList all roles
POST/api/v1/rolesCreate a role
PATCH/api/v1/roles/:roleIdUpdate a role
DELETE/api/v1/roles/:roleIdDelete a role

GET /api/v1/roles

Response 200

{
  "roles": [
    {
      "id": "role_abc",
      "key": "admin",
      "name": "Admin",
      "description": "Full access",
      "permissions": ["*"],
      "is_default": false
    },
    {
      "id": "role_def",
      "key": "member",
      "name": "Member",
      "description": "Read-only access",
      "permissions": ["documents:read"],
      "is_default": true
    }
  ]
}

POST /api/v1/roles

Request body

{
  "key": "editor",
  "name": "Editor",
  "description": "Can read and write documents",
  "permissions": ["documents:read", "documents:write", "comments:write"]
}

Response 201

{
  "role": {
    "id": "role_ghi",
    "key": "editor",
    "name": "Editor",
    "description": "Can read and write documents",
    "permissions": ["documents:read", "documents:write", "comments:write"],
    "is_default": false,
    "created_at": "2025-01-15T10:00:00Z"
  }
}

PATCH /api/v1/roles/:roleId

Update name, description, permissions, or set as default. All fields are optional.

Request body

{
  "name": "Content Editor",
  "permissions": ["documents:read", "documents:write", "documents:delete", "comments:write"],
  "is_default": false
}

Updating a role's permissions applies immediately to all members who hold that role across every organization in the project.

DELETE /api/v1/roles/:roleId

Returns 409 if the role is currently assigned to one or more members. Reassign or remove those members before deleting the role.

See Roles & Permissions for how to define permission strings and use wildcard matching.

Was this page helpful?