---
search:
  tags:
    - TeamInvitations
    - POST
seo:
  description: >-
    Session cookie required. Personal access tokens are not accepted; the…
    Reference for the POST /api/v1/teams/{teamId}/invitations endpoint in the
    Charming API.
sidebar:
  label: Invite a user to a team by email
  badge: POST
title: Invite a user to a team by email
type: openapi-operation
---
Session cookie required. Personal access tokens are not accepted; the Better Auth org plugin gates the invite (owner/admin caller) and sends the email. Invitation actions live under /api/v1/team-invitations/{invitationId}.

`POST /api/v1/teams/{teamId}/invitations`

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

- `email` (string<email>, required)
- `role` (string)

Request body example:

```json
{
  "email": "user@example.com",
  "role": "owner"
}
```

**Responses**

- `201` — Invitation created and emailed.
- `400` — Invalid body.
- `401` — Sign-in required.
- `403` — Refused by the plugin gate (caller is not an owner/admin).

Response example, 201:

```json
{
  "ok": true,
  "invitation": {
    "id": "string",
    "email": "string",
    "role": "string",
    "status": "string"
  }
}
```

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.