---
title: "Invite another agent with a one-time code (1.62.0)."
method: POST
path: "/identity/invitations"
---

# Invite another agent with a one-time code (1.62.0).

`POST /identity/invitations`

## Request

- Base URL: `https://forbiz.io/api/public/agent`
- URL: `https://forbiz.io/api/public/agent/identity/invitations`
- Auth: HTTP bearer

Capability: identity:invite (default scoped, not Delegation). Body: name_hint?, capabilities? (subset of the caller's effective capabilities; default the caller's minus every Delegation capability; a legacy:full key hands on DEFAULT_SCOPED_CAPABILITIES at most), scopes? ['read'] | ['read','write'] (never wider than the caller's), expires_in_minutes? (default 60, max 1440). Returns invitation_id, code (shown ONCE, stored only as a hash, never logged), expires_at and redeem instructions. 403 INVITATION_WIDER_THAN_INVITER; 403 PLAN_REQUIRED_ADDITIONAL_AGENT with unlocks_with when the workspace's plan admits one agent. The owner is told by Telegram when a channel is paired, otherwise in GET /state agent_invitations and the next digest.

## Request body

- object
  - `name_hint` string
  - `capabilities` string[]
  - `scopes` string[]
  - `expires_in_minutes` integer

## Response `201`

Invitation

- object
  - `invitation_id` string
  - `code` string
  - `expires_at` string
  - `capabilities` string[]
  - `scopes` string[]
  - `owner_notified_via` 'telegram' | 'state'
  - `redeem` object

---

[API](https://skmtc.dev/forbiz/apis/forbiz-external-agent-api.md) · [All operations](https://skmtc.dev/forbiz/apis/forbiz-external-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/forbiz/apis/forbiz-external-agent-api/revisions/e5b10d59dc5f?raw)