> ## Documentation Index
> Fetch the complete documentation index at: https://opentrain.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Grant Permission

> Grant or update a user's role on an instruction workspace.

Grants a workspace role to a user — or, when the user already holds one, updates it (upsert). The `OWNER` role cannot be granted; workspace creation persists it for the owner.

**Requirements:** `instructions:publish` + workspace `OWNER` + a verified (claimed) account.

## Request

<ParamField path="workspaceId" type="string" required>
  The workspace id.
</ParamField>

<ParamField body="principalId" type="string" required>
  The user id receiving the role.
</ParamField>

<ParamField body="role" type="string" required>
  `EDITOR` (author changesets), `REVIEWER` (decide submitted changesets), or `VIEWER` (read only).
</ParamField>

## Response

<ResponseField name="permission" type="object">
  The created or updated permission record.
</ResponseField>