---
title: "Invite user to workspace"
method: POST
path: "/workspaces/invitations"
tags: ["WorkspaceInvitation"]
---

# Invite user to workspace

`POST /workspaces/invitations`

Create link or email based workspace invite. For email invites, invite emails are sent to the invited users.

## Request body

- CreateOrganizationInvitationRequest
  - `invitee_email` string — The e-mail address allowed to accept a EMAIL based invitation. Required for EMAIL based invitations.
  - `allow_list_emails` string[] — The e-mail addresses allowed to accept a LINK based invitation. Required for LINK based invitations.
  - `validity_seconds` integer — The number of seconds this invite should be valid for
  - `invitee_role` UserRole, required
    - `role` 'owner' | 'editor' | 'viewer', required — The possible values for user role
    - `workspace_id` string — The workspace this role applies to. Preferred over `organization_id`. At least one of `workspace_id` or `organization_id` must be present.
    - `organization_id` string — Deprecated alias for `workspace_id`. Retained so legacy callers keep working; new code should use `workspace_id`.
    - `acknowledged_status` 'requires_acknowledgement' | 'acknowledged' — Status marking whether the user has acknowledged the welcome message in the joined workspace
  - `app_host` string — Mabl app site host. Defaults to current app.
  - `accept_uri_template` InvitationAcceptUriTemplate — Deprecated. Use the top-level `app_host` field instead. Retained for backward compatibility.
    - `template` string, required — The URI template containing variables that will be substituted by the server
    - `invitation_id_variable` string, required — The variable in the template into which the invitation ID should be substituted
  - `invite_type` 'email' | 'link'

## Response `201`

The created invitation

- OrganizationInvitation
  - `id` string — The ID of the organization invitation
  - `created_time` integer — Time at which the organization invitation was created
  - `created_by_id` string — The ID of the user who created this organization invitation
  - `last_replayed_time` integer — Time at which the organization invitation was last replayed (re-sent)
  - `last_updated_time` integer — Time at which the organization invitation was last updated
  - `last_updated_by_id` string — The ID of the user who last updated this organization invitation
  - `invitee_email` string — The e-mail address to which the invitation should be sent (singular recipient)
  - `invite_type` 'email' | 'link'
  - `allow_list_emails` string[] — The e-mail addresses that are allowed to accept this invitation (when invite supports multiple invitees)
  - `expiration_time` integer — The timestamp that this invitation is valid until (max 7 days)
  - `invitee_role` UserRole
    - `role` 'owner' | 'editor' | 'viewer', required — The possible values for user role
    - `workspace_id` string — The workspace this role applies to. Preferred over `organization_id`. At least one of `workspace_id` or `organization_id` must be present.
    - `organization_id` string — Deprecated alias for `workspace_id`. Retained so legacy callers keep working; new code should use `workspace_id`.
    - `acknowledged_status` 'requires_acknowledgement' | 'acknowledged' — Status marking whether the user has acknowledged the welcome message in the joined workspace
  - `acceptance_api_key_id` string — ID of key that backs this invite.
  - `accepted_by_emails` string[] — Email addresses that have accepted this invitation (link-type only)
  - `accept_uri` string — The URI that the user should request in order to accept the invitation. Only returned upon creation for Link type invites, otherwise passed via invite email.
  - `accept_uri_host` string — Mabl app site host. Defaults to current app.
  - `accept_uri_query_string` string — Non-secret query parameters chosen at creation to populate the invite link.
  - `is_expired` boolean — Whether this invitation has effectively expired (server-resolved)
  - `created_by_name` string — Display name of the user who created this invitation (server-resolved)
  - `tags` Tag[] — Free text tags associated with this entity
    - `name` string, required — tag name
    - `values` string[]

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `404` — Entity not found
- `409` — Invitation already exists for the specified e-mail address and workspace
- `429` — Too many requests
- `default` — Unknown error

---

[API](https://skmtc.net/mabl/apis/mabl-api.md) · [All operations](https://skmtc.net/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mabl/mabl-api/revisions/d0fc0114da66/schema)