Permissions

Last verified: 2026-06-20 (Task #390 — User APIs documentation).

Trips are collaborative. Each collaborator has a role — owner, planner, editor, or viewer (see the role table in authentication.md).

List collaborators

GET /v1/trips/{tripId}/permissions

Requires trip membership (any role).

{
  "trip_id": 42,
  "permissions": [
    { "user_id": "usr_owner", "role": "owner", "granted_at": "2026-06-01T10:00:00.000Z" },
    { "user_id": "usr_8c1f", "role": "planner", "granted_by_user_id": "usr_owner", "granted_at": "2026-06-02T09:00:00.000Z" }
  ]
}

Grant or update a role

POST /v1/trips/{tripId}/permissions

Owner-only. Grants a role to a user, or updates their existing role.

curl -s -X POST "https://api.travelmode.ai/v1/trips/42/permissions" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "usr_8c1f", "role": "planner" }'

{ "trip_id": 42, "user_id": "usr_8c1f", "role": "planner", "granted_by": "usr_owner" }

A non-owner caller gets 403 ({ "error": "Only the trip owner can manage permissions" }). An unknown target user gets 404.

Revoke a collaborator

DELETE /v1/trips/{tripId}/permissions/{userId}

Owner-only. Removes a user's permission row.

curl -s -X DELETE "https://api.travelmode.ai/v1/trips/42/permissions/usr_8c1f" \
  -H "Authorization: Bearer <token>"

{ "trip_id": 42, "user_id": "usr_8c1f", "revoked": true }

The owner's own permission cannot be revoked — attempting it returns 400 ({ "error": "Cannot revoke the trip owner" }). Revoking a user who has no permission row returns 404.