Permissions API

Endpoints that manage a survey's sharing permissions.

See API Definition for authentication, response format, and error handling.

Method

HTTP Methods

Method	URI	Overview
GET	/api/surveys/{surveyId}/permissions	List permissions
PUT	/api/surveys/{surveyId}/permissions	Bulk-update permissions

Resource Definition

Permission Levels

Permission	Value	What it allows
View	view	Viewing the survey, previewing, viewing version history, duplicating surveys and versions
Edit	edit	Everything view allows, plus updating the theme, editing sections and questions, saving, exporting, and changing permissions

Administrators (users listed in SURVEY_ADMIN_EMAILS) can view and edit every survey regardless of permission records.

Permission Schema

Field	Type	Notes
userId	string	User UUID
userName	string	User display name
roleType	enum	view / edit

Authentication

User authentication via the x-user-email / x-user-name headers is required.

Operation	Required permission
Listing permissions	view
Bulk-updating permissions	edit

Missing permission returns 404 Not Found.

List Permissions

Overview

Returns the survey's sharing permission list.

URI

GET /api/surveys/{surveyId}/permissions

Parameter	Type	Required	Notes
surveyId	string	◯	Survey UUID

Response (200 OK)

{
  "ok": true,
  "data": [
    { "userId": "…", "userName": "設計 太郎", "roleType": "edit" },
    { "userId": "…", "userName": "レビュー 花子", "roleType": "view" }
  ]
}

Error Handling

Description	Status code	Status name
Survey does not exist, or view permission is missing	404	Not Found

Bulk-update Permissions

Overview

Replaces the survey's sharing permissions wholesale. What is sent becomes the permission list, so existing permissions that should stay must be included as well.

URI

PUT /api/surveys/{surveyId}/permissions

Request Body

{
  "permissions": [
    { "userId": "…", "userName": "設計 太郎", "roleType": "edit" },
    { "userId": "…", "userName": "レビュー 花子", "roleType": "view" }
  ]
}

Validation Rules

Field	Rule
permissions	Required. An array holding the full permission set
permissions[].userId	Required. UUID of an existing user
permissions[].userName	Required. String
permissions[].roleType	Required. One of view / edit

In addition, anyone who is not an administrator must include their own edit permission in the array. Sending it without them is an error.

Response (200 OK)

Returns the updated permission list.

Error Handling

Description	Status code	Status name
Malformed request body	400	Bad Request
A given user does not exist	404	Not Found
A non-administrator tried to remove their own edit permission	404	Not Found
Survey does not exist, or edit permission is missing	404	Not Found

Validation errors also return 404

Validation errors are caught in the handler and returned as 404 with an error message ("存在しないユーザーを権限に設定することはできません。", "自分自身の編集権限は外せません。"). Distinguish the cause from the error text rather than the status code.

Processing Flow

Sequence Diagram

sequenceDiagram
    participant Client
    participant API
    participant DB

    Client->>API: PUT /api/surveys/{surveyId}/permissions
    API->>API: Check edit permission
    API->>DB: Verify the given users exist
    alt Some user is missing
        API-->>Client: 404 (user does not exist)
    else Non-administrator omitted their own edit permission
        API-->>Client: 404 (cannot remove your own edit permission)
    else
        API->>DB: Begin transaction
        API->>DB: Delete all existing permissions
        API->>DB: Insert the given permissions
        API->>DB: Commit
        API-->>Client: 200 OK
    end

You cannot remove your own edit permission

The update reflects exactly what was sent, but a non-administrator who omits their own edit permission gets an error and the update does not happen at all. It is impossible to lock yourself out by mistake. Administrators are not subject to this restriction.