---
title: "Invite a user to a team by email"
method: POST
path: "/api/v1/teams/{teamId}/invitations"
tags: ["TeamInvitations"]
---

# Invite a user to a team by email

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

## Request

- Base URL: `https://charm.ing`
- URL: `https://charm.ing/api/v1/teams/{teamId}/invitations`
- Auth: API key in cookie `__Secure-better-auth.session_token`

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}.

## Path parameters

- `teamId` string, required

## Request body

- object
  - `email` string, email, required
  - `role` 'owner' | 'admin' | 'member'

## Response `201`

Invitation created and emailed.

- TeamInvitationCreateResponse
  - `ok` true, required
  - `invitation` object, required
    - `id` string, required
    - `email` string, required
    - `role` string, required
    - `status` string, required

## Other responses

- `400`: Invalid body.
- `401`: Sign-in required.
- `403`: Refused by the plugin gate (caller is not an owner/admin).

---

[API](https://skmtc.dev/charm/apis/charming-api.md) · [All operations](https://skmtc.dev/charm/apis/charming-api/llms.txt) · [OpenAPI document](https://skmtc.dev/charm/apis/charming-api/revisions/a9d06c419b3a?raw)