Members and permissions

The Permissions API runs Synq's team and access-control model: it reports whether the active org is a team, lists the resources you can grant, creates a team organization, and manages the per-member grants and invitations that scope a restricted member to specific projects, servers, or other resources. In the dashboard this is the organization's Team tab. See Auth & access for how roles and grants combine.

User grants give a restricted member access to specific resources. Roles also provide their standard permissions. Token grants and read-only restrictions are an additional limit for every role. A user grant is (user, resourceType, resourceId, permissions[]); resourceId: "*" applies across the organization.

Create a team organization

Creates a brand-new organization, marks it as a team, and sets the caller as its owner. Personal workspaces stay personal — this is the way to get a shared, multi-member org.

const result = await ship.permissions.createTeamOrg({
  name: "Acme Platform",
});
console.log(result);

curl -X POST "$SYNQ_URL/api/permissions/create-team-org" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Platform"}'

Returns 201 with { data: { id, name, isTeam: true } }.

List grantable resources

Side-effect-free picker payload for the grant modal and invite flow. Pass the resource type; get back { id, label, meta? }[]. The * wildcard is not listed — the picker adds it itself.

const result = await ship.permissions.listResources({
  type: "server",
});
console.log(result);

curl "$SYNQ_URL/api/permissions/resources?type=server" \
  -H "Authorization: Bearer $SYNQ_TOKEN"

For type=billing or type=audit the only entry is the org-wide *. For type=github_repository you can narrow to one account with &owner=<login>.

Grant a resource

Idempotent upsert of a single grant tuple. Re-sending the same (userId, resourceType, resourceId) replaces its permissions in place. An empty permissions array revokes the grant (Synq keeps no zero-permission placeholder rows).

const result = await ship.permissions.upsertGrant({
  userId: "user_123",
  resourceType: "project",
  resourceId: "proj_abc",
  permissions: ["read", "write"],
});
console.log(result);

curl -X POST "$SYNQ_URL/api/permissions/grants" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userId":"user_123","resourceType":"project","resourceId":"proj_abc","permissions":["read","write"]}'

Returns 201 with { data: <grant> }, or { data: null, revoked: true } when permissions was empty.

Replace a member's grant set

Sends the member's entire desired grant set; the server diffs against what exists — upserting added/changed tuples and deleting any that are absent. This is the single save path for the member-grants editor. Zero-permission entries are dropped.

const result = await ship.permissions.replaceGrants({
  userId: "user_123",
  grants: [
    {
      resourceType: "project",
      resourceId: "proj_abc",
      permissions: ["read", "write"],
    },
    {
      resourceType: "server",
      resourceId: "srv_1",
      permissions: ["read"],
    },
  ],
});
console.log(result);

curl -X PUT "$SYNQ_URL/api/permissions/grants" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId":"user_123",
    "grants":[
      {"resourceType":"project","resourceId":"proj_abc","permissions":["read","write"]},
      {"resourceType":"server","resourceId":"srv_1","permissions":["read"]}
    ]
  }'

Each entry of grants is a Grant object:

Non-wildcard, row-backed resources are checked to belong to the active org; a foreign id is rejected with 400 RESOURCE_NOT_IN_ORG.

Invite a member with grants

Wraps Better Auth's invite and, in the same call, stores pending grants against the invitation. When the invitee accepts, the accept-invite page calls POST /invitations/:id/materialize to turn those pending grants into real ones.

const result = await ship.permissions.inviteWithGrants({
  email: "dev@acme.com",
  role: "restricted",
  grants: [
    {
      resourceType: "project",
      resourceId: "proj_abc",
      permissions: ["read", "write"],
    },
  ],
});
console.log(result);

curl -X POST "$SYNQ_URL/api/permissions/invite-with-grants" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email":"dev@acme.com",
    "role":"restricted",
    "grants":[{"resourceType":"project","resourceId":"proj_abc","permissions":["read","write"]}]
  }'

Returns 201 with { data: { id, email, role, pendingGrantCount } }.

Materialize an invitation's grants

Called from the accept-invite page after Better Auth records the acceptance. It finds the invitation's pending grants, upserts them as real grants for the now-joined user, and clears the pending rows. Authorized by the invitation itself — the caller's email must match the invite and its status must be accepted.

const result = await ship.permissions.materializeInvitation("inv_123");
console.log(result);

curl -X POST "$SYNQ_URL/api/permissions/invitations/inv_123/materialize" \
  -H "Authorization: Bearer $SYNQ_TOKEN"

Returns { data: { materialized: <count> } }.

Errors

Operations