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

# Add Workspace User

> Requires `workspace-users-write`. Add an existing user or send an invite if the email is unknown. Self-hosted Community instances are limited to 2 users total across the instance; adding or inviting more users requires a self-hosted Enterprise license.

# Add Workspace User

Invite an existing OpnForm user to a workspace or send an email invite if the user doesn't yet have an account.

<Note>
  Self-hosted Community instances are limited to 2 users total across the whole instance. Adding or inviting a new user beyond that limit requires a self-hosted Enterprise license. Adding an existing instance user to another workspace does not consume an additional user seat.
</Note>

## Authentication & Scope

Requires the `workspace-users-write` ability and **admin** privileges in the workspace.

## Request

```http theme={null}
POST /open/workspaces/{workspaceId}/users/add HTTP/1.1
Host: api.opnform.com
Content-Type: application/json
Authorization: Bearer <token>
```

### Path Parameters

| Parameter   | Type   | Description                 |
| ----------- | ------ | --------------------------- |
| workspaceId | number | ID of the target workspace. |

### Body Parameters

| Field | Type   | Required | Description                                      |
| ----- | ------ | -------- | ------------------------------------------------ |
| email | string | Yes      | Email address of the user to add/invite.         |
| role  | string | Yes      | Role to assign (`admin`, `user`, or `readonly`). |

Example:

```json theme={null}
{
  "email": "jane@example.com",
  "role": "user"
}
```

## Response

`200 OK` – One of the following messages:

* `"User has been successfully added to workspace."` – when the user account already exists.
* `"Registration invitation email sent to user."` – when an invitation email was sent.
* `"User is already in workspace."` – if the user is already a member.

The response structure:

```json theme={null}
{
  "message": "User has been successfully added to workspace."
}
```

`403 Forbidden` – Token lacks `workspace-users-write`, the requester has insufficient privileges, or the self-hosted Community instance has reached the 2-user limit.


## OpenAPI

````yaml post /open/workspaces/{workspaceId}/users/add
openapi: 3.0.1
info:
  title: OpnForm API
  description: API for interacting with OpnForm, primarily used for Zapier integration
  version: 1.0.0
servers:
  - url: https://api.opnform.com
security:
  - bearerAuth: []
tags:
  - name: Workspaces
    description: Create and manage workspaces.
  - name: Workspace Users
    description: Manage users within a workspace.
  - name: Forms
    description: Manage and retrieve forms.
  - name: Submissions
    description: Access and manage form submissions.
  - name: Integrations
    description: Manage form integrations (webhooks) via API.
  - name: Zapier
    description: Legacy endpoints for the Zapier integration.
paths:
  /open/workspaces/{workspaceId}/users/add:
    post:
      tags:
        - Workspace Users
      summary: Add Workspace User
      description: >-
        Requires `workspace-users-write`. Add an existing user or send an invite
        if the email is unknown. Self-hosted Community instances are limited to
        2 users total across the instance; adding or inviting more users
        requires a self-hosted Enterprise license.
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - role
              properties:
                email:
                  type: string
                  format: email
                role:
                  type: string
                  enum:
                    - admin
                    - user
                    - readonly
      responses:
        '200':
          description: User added
        '403':
          description: >-
            Forbidden, insufficient privileges, or self-hosted Community user
            limit reached
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Personal Access Token
      x-bearer-scopemap:
        workspaces-read: Read access to workspaces
        workspaces-write: Write access to workspaces
        workspace-users-read: Read access to workspace users
        workspace-users-write: Write access to workspace users
        forms-read: Read access to forms
        forms-write: Write access to forms
        manage-integrations: Manage form integrations (webhooks)

````