Permissions API

The Permissions API runs Openship's team and access-control model: it reports whether the active org is a team, lists the resources you can grant, upgrades a personal workspace into a team org, 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.

Endpoints

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.

POST /api/permissions/create-team-org

curl -X POST https://your-host/api/permissions/create-team-org \
  -H "Authorization: Bearer $OPENSHIP_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.

GET /api/permissions/resources?type=project

curl "https://your-host/api/permissions/resources?type=server" \
  -H "Authorization: Bearer $OPENSHIP_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 (Openship keeps no zero-permission placeholder rows).

POST /api/permissions/grants

curl -X POST https://your-host/api/permissions/grants \
  -H "Authorization: Bearer $OPENSHIP_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.

PUT /api/permissions/grants

Each entry of grants is a Grant object:

curl -X PUT https://your-host/api/permissions/grants \
  -H "Authorization: Bearer $OPENSHIP_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"]}
    ]
  }'

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.

POST /api/permissions/invite-with-grants

curl -X POST https://your-host/api/permissions/invite-with-grants \
  -H "Authorization: Bearer $OPENSHIP_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.

POST /api/permissions/invitations/:id/materialize

curl -X POST https://your-host/api/permissions/invitations/inv_123/materialize \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

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

Errors you might see