---
title: "Grant permission"
method: POST
path: "/forms/{formId}/permissions"
tags: ["Permissions"]
---

# Grant permission

`POST /forms/{formId}/permissions`

Grants a role on a form to a user or a group. Requires MANAGE permission.

## Request body

- union
  - object
    - `role` 'view' | 'respond' | 'comment' | 'analyze' | 'edit' | 'manage', required
    - `user` string, email, required
    - `group` string, ulid
  - object
    - `role` 'view' | 'respond' | 'comment' | 'analyze' | 'edit' | 'manage', required
    - `user` string, email
    - `group` string, ulid, required

## Response `201`

Permission granted successfully.

- Permission
  - `id` string, ulid, required
  - `form` string, ulid, required
  - `role` 'view' | 'respond' | 'comment' | 'analyze' | 'edit' | 'manage', required
  - `user` string, ulid, nullable
  - `group` string, ulid, nullable

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Conflict
- `422` — Unprocessable Entity

## Changes

- **2025-07-14** `9aec27988ad3` — 1 breaking
  - the `user` request property type/format changed from `string`/`ulid` to `string`/`email`
- **2025-07-13** `0d7f3c750979` — 1 breaking
  - the `user` request property type/format changed from `string`/`email` to `string`/`ulid`

[Change history](https://skmtc.dev/osdg-iiith/apis/forms-portal-api/changes/forms/:formId/permissions/post.md)

---

[API](https://skmtc.dev/osdg-iiith/apis/forms-portal-api.md) · [All operations](https://skmtc.dev/osdg-iiith/apis/forms-portal-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/osdg-iiith/forms-portal-api/revisions/7761ba23f677/schema)