---
title: "Invite a teammate with a one-time API link"
method: POST
path: "/api/invites"
tags: ["Users"]
---

# Invite a teammate with a one-time API link

`POST /api/invites`

## Request

- Base URL: `http://localhost:3013`
- URL: `http://localhost:3013/api/invites`
- Auth: HTTP bearer

Creates an invited user with the given role (requester by default) and returns a 7-day single-use API link. The API redirects to the current APP_URL dashboard with the code in the URL fragment. The browser exchanges the code at POST /api/invites/exchange for a personal MCP token. Re-inviting an invited user replaces the role and link. Active or suspended users return 409 user_exists. No email is sent.

## Request body

- object
  - `email` string, email, required
  - `name` string
  - `role` 'requester' | 'viewer' | 'admin'

## Response `201`

The invited user, API link, dashboard URL, expiry and API reachability

- object
  - `user` object, nullable, required
    - `id` string, required
    - `name` string, required
    - `email` string
    - `role` string
    - `notes` string
    - `emailAliases` string[]
    - `preferredChannel` string
    - `timezone` string
    - `metadata` object
    - `dailyBudgetUsd` number, nullable
    - `status` 'invited' | 'active' | 'suspended'
    - `createdAt` string, date-time, required
    - `lastUpdatedAt` string, date-time, required
    - `identities` object[], required
      - `kind` string, required
      - `externalId` string, required
    - `tokens` object[], required
      - `id` string, required
      - `userId` string, required
      - `label` string, nullable, required
      - `tokenPreview` string, required
      - `createdAt` string, required
      - `lastUsedAt` string, nullable, required
      - `revokedAt` string, nullable, required
    - `recentEvents` object[], required
      - `id` string, required
      - `userId` string, required
      - `eventType` string, required
      - `actor` string, required
      - `before` unknown
      - `after` unknown
      - `createdAt` string, required
  - `inviteUrl` string, required
  - `appUrl` string, required
  - `expiresAt` string, required
  - `apiReachable` 'public' | 'local', required

## Other responses

- `401`: Unauthorized
- `403`: Not allowed to manage roles
- `409`: The email belongs to an active or suspended user

## Changes

- **2026-10-27** `b6cfdb1f4830`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/invites/post.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) - [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/revisions/7e4c7198192a?raw)