---
search:
  tags:
    - AppShares
    - POST
seo:
  description: >-
    User-gated (chrm_user_* or session); owner only (app:share). Creates a…
    Reference for the POST /api/v1/apps/{appId}/shares endpoint in the Charming
    API.
sidebar:
  label: Invite a user to an app
  badge: POST
title: Invite a user to an app
type: openapi-operation
---
User-gated (`chrm_user_*` or session); owner only (`app:share`). Creates a pending invitation — `status: "pending"` for an existing account, `"invited"` for an email with no account yet. No access is granted until the grantee accepts.

`POST /api/v1/apps/{appId}/shares`

**Request body** (`application/json`, required)

- `grantee` (string, required) — Handle or email of the invitee.
- `role` (string)

Request body example:

```json
{
  "grantee": "string",
  "role": "collaborator"
}
```

**Responses**

- `201` — Invitation created.
- `400` — Invalid body or app id.
- `401` — Sign-in required.
- `403` — Only the owner can manage shares.
- `404` — App not found, or no account for the grantee handle.
- `409` — Unshareable state (unclaimed app, self-share, existing access, or pending invitation).
- `429` — Share-lookup rate limit or invitation cap.

Response example, 201:

```json
{
  "ok": true,
  "status": "pending"
}
```

Found a bug or need a feature? [Tell us](/docs/capabilities/feedback) with `submit_feedback` or `POST /app/{id}/feedback`. Your feedback shapes what we build next.