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

# Invite a Teammate

> Invite someone into a Tuco workspace by email, with a role, using that workspace's API key.

<Note>
  Adds an existing Tuco user to the workspace immediately, or emails an invitation to
  someone who does not have an account yet.
</Note>

## Endpoint

* **Method**: `POST`
* **Path**: `/api/team/invite`
* **Auth**: `Authorization: Bearer tuco_xxxxxxxxxxxxx`

## Body

| Field | Type | Required | Notes |
| - | - | - | - |
| `email` | string | yes | Who to invite |
| `role` | string | no | `org:member` (default) or `org:admin` |

## Example request

```bash theme={null}
curl https://app.tuco.ai/api/team/invite \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "owner@acmeroofing.com", "role": "org:admin"}'
```

## Success response (200)

```json theme={null}
{
  "ok": true,
  "status": "invited",
  "email": "owner@acmeroofing.com",
  "inviteUrl": "https://accounts.tuco.ai/v1/tickets/accept?ticket=…",
  "inviteId": "orginv_…"
}
```

| `status` | Meaning |
| - | - |
| `added` | They already had a Tuco account and are now a member. No email was sent — share the login link yourself |
| `invited` | An invitation email was sent. `inviteUrl` is the same link if you want to deliver it your own way |
| `already_member` | Nothing to do |

## Permissions

A signed-in caller must be a workspace admin. An **API key** is accepted on its own:
only a workspace owner or admin can mint one, and it is scoped to this workspace, so
the key already carries the authority the check would test. This also means an
integration keeps working when the person who created the key changes role or leaves.

Agencies: use the workspace key for the workspace you are inviting into — the one
returned by [Create Agency Workspace](/api-reference/endpoint/agency-create-workspace).
An agency key cannot invite, because "which workspace?" would be ambiguous.

## Error responses

| Status | When |
| - | - |
| `400` | `email` missing, or `role` is not `org:admin` / `org:member`, or no active workspace |
| `401` | Missing or invalid key |
| `403` | A signed-in non-admin, or an agency key (`tucoagency_…`) |
| `500` | The invitation could not be created |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.