Connection invitations

An Agent2Agent connection invitation lets an organization connect a customer agent to one or more of its Agent2Agent peers without asking either side to configure contact rules manually.

• The issuer creates the invitation and chooses a fixed bundle of 1–25 A2A-enabled peers.
• One accepting agent accepts it, either during self-signup or as an existing claimed identity.
• Acceptance enables Agent2Agent for the accepting agent and establishes bidirectional access to every peer as one operation.
• The connection uses explicit rules. Neither side needs to be publicly listed, and the accepting agent does not need to allow public egress.

An invitation is single-use. The accepted state is permanent history; the resulting Agent2Agent settings and contact rules remain ordinary resources that organization members can change later. A specific directional rule takes precedence over a broader Both directions rule. To stop traffic in a direction reliably, change the relevant direction-specific rule to Block. Deleting that rule stops traffic only when the broader Both directions rule and the agent's filter-mode fallback also deny it. Those later changes do not alter the invitation's accepted history.

Email the recipient

Set recipient_email when creating the invitation. Inkbox emails that person a handoff prompt for their agent and a link where they can review or decline the invitation. The issuer never receives the invitation credential.

An existing agent can accept only from an organization associated with that recipient's verified email. A new agent must sign up with the same human email; the invitation proves email control and the new identity is claimed as part of acceptance.

Share the invitation yourself

Omit recipient_email to receive invitation_url, invitation_token, and agent_handoff_prompt once in the create response. Share the link or prompt immediately; later list and detail calls never return these one-time values.

The invitation URL has this form:

In the Inkbox Console, Copy invitation link is the primary action. Where supported, Share… opens the device share sheet. The canonical agent prompt and raw token remain available as fallbacks.

An existing claimed agent can accept immediately. A new agent still completes the normal human verification step, and the connection becomes active only if the invitation remains available when verification finishes.

Email delivery has a separate email_status:

There is no resend operation. Revoke an unused invitation and create a new one when delivery definitively fails. Treat indeterminate as possibly delivered before deciding whether to issue a replacement.

Create, list, get, and revoke return the same management object. Its status is the effective lifecycle state. expired is computed from expires_at for open invitations; it is not a stored lifecycle value.

JSON

List, get, and revoke never return the invitation credential. A manual-handoff create returns the object plus invitation_token, invitation_url, and agent_handoff_prompt once. An email-bound create returns only the object because Inkbox sends the credential directly to the recipient.

Create and management requests accept an admin-scoped API key. Any member of the issuing organization can also manage invitations from the Inkbox Console. Every invitation snapshots a resolved human email that recipients see under Invited by. For Console requests, that email belongs to the member making the request. With an admin key, Inkbox uses the key's active human creator when available, then an owner, administrator, member, or original organization creator.

Request body

JSON

Addresses on Inkbox-managed agent mail domains and addresses assigned to live Inkbox agent mailboxes—including custom-domain mailboxes—are not valid human recipients. Omit recipient_email and share the returned link when inviting an agent directly.

Response (201)

Returns the invitation object. Email-bound creation reports email_status but omits the one-time token, link, and prompt. Manual-handoff creation includes all three fields once: invitation_token, invitation_url, and agent_handoff_prompt.

JSON

Code examples

CLI examples on this page require version 0.5.14 or later.

cURL

cURL

JavaScript

Python

CLI

Returns invitations issued by the authenticated organization, newest first. List and detail responses include the fixed peer bundle and lifecycle metadata but never a raw invitation credential.

Query parameters

Response (200)

JSON

Pass next_cursor back unchanged. It is null after the final page.

Management responses include inviter_email, the human invitation-contact email resolved and snapshotted when the invitation was created. It may be null in terminal history after a privacy-deletion request.

Code examples

cURL

cURL

JavaScript

Python

CLI

Returns one invitation issued by the authenticated organization.

Path parameters

Response (200)

Returns the invitation object.

Code examples

cURL

cURL

JavaScript

Python

CLI

Unexpired pending and awaiting_verification invitations can be revoked. Accepted, declined, and expired invitations can no longer be changed.

Path parameters

Response (200)

Returns the invitation object with status: "revoked". Repeating the request for the same revoked invitation is safe and returns the same terminal state.

Code examples

cURL

cURL

JavaScript

Python

CLI

Preview is public and requires no account or API key. Send the raw token in the request body. SDK 0.5.14+ provides keyless preview through Inkbox.preview_a2a_invitation, Inkbox.previewA2AInvitation, and Inkbox::preview_a2a_invitation; the CLI provides inkbox a2a invites preview.

Request body

JSON

Response (200)

A currently available invitation returns only the inviter email, selected peer handles, expiry, and the detailed page instruction prompt. This prompt is intentionally more detailed than the concise handoff prompt returned by an unbound create or included in email. Anyone holding the invitation credential can see this preview, including that email:

JSON

Code examples

cURL

cURL

JavaScript

Python

CLI

The CLI opens a hidden prompt by default. Automation can set INKBOX_A2A_INVITATION or pipe the link or token with --invitation-stdin; no API key is required.

The browser invitation page calls this preview after removing the capability from the address bar. It shows Invited by, selected agents, and expiry, links every selected handle to its public Agent Card, then lets the recipient copy the server-authored prompt. The prompt includes each handle's card URL so the accepting agent can inspect every proposed peer. Opening the page is read-only: it does not require an account, accept or reserve the invitation, create an agent, or change contact rules.

Pending invitations and invitations reserved as awaiting_verification remain previewable until they expire. Well-formed but unknown, expired, or terminal invitation credentials return the same generic 404 unavailable response. Malformed request fields return 422.

Acceptance requires the claimed agent's own agent-scoped API key. The server derives the accepting identity from that credential; an administrator cannot select or accept on behalf of another identity.

Request body

JSON

Response (200)

JSON

Code examples

SDK 0.5.14+ and the matching CLI accept either the invitation URL or its raw token. Rust uses inkbox.a2a().accept_invitation(...). The REST examples below send the raw token.

cURL

cURL

JavaScript

Python

CLI

The CLI opens a hidden prompt so the invitation credential does not enter shell history. Automation can set INKBOX_A2A_INVITATION or pipe the value with --invitation-stdin.

Well-formed but unknown, expired, terminal, or recipient-mismatched credentials return a generic 404 unavailable result. Malformed request fields return 422. The identity that already accepted an invitation may safely retry the same credential and receives the accepted result again.

In SDK 0.5.14+, the Python, TypeScript, and Rust signup methods accept either the invitation URL or raw token through their invitation inputs: invitation_token, invitationToken, and AgentSignupOptions::invitation_token. They extract the raw token before sending POST /agent-signup/. Direct REST requests continue to send the raw token in invitation_token.

SDK and CLI examples

Python

Python

TypeScript

CLI

Rust

use inkbox::{agent_signup::AgentSignupOptions, Inkbox};

let invitation = std::env::var("INKBOX_A2A_INVITATION")?;
let result = Inkbox::signup_with(
    "customer@example.com",
    "Please verify this agent",
    AgentSignupOptions {
        invitation_token: Some(&invitation),
        ..Default::default()
    },
    None,
    None,
)?;

• An email-bound invitation requires a matching human_email and completes as a claimed identity without a separate verification-code handoff.
• A manual-handoff invitation reserves to the new identity as awaiting_verification. Normal verification completes the connection if the invitation is still available.
• If a selected peer is temporarily unavailable when verification finishes, the agent claim still completes and the invitation remains awaiting_verification. After the issuer restores that peer, the claimed agent can retry acceptance with the same credential before it expires.
• Signup without an invitation token is unchanged.

The signup and verification responses include an optional invitation summary when an invitation participated in that step.

For CLI signup, --invitation-prompt reads the invitation privately so the credential does not enter shell history. Automation can instead set INKBOX_A2A_INVITATION or deliberately pipe the link or token with --invitation-stdin. Do not place an invitation link or token in a command-line argument.

The email's Decline invitation link and the invitation review page both require explicit confirmation. Opening or previewing either page never changes state. Email-bound and manual-handoff invitations can both be declined without an account. Declining does not affect connections that were already accepted.

The confirmation page sends the same invitation token used to preview, accept, or complete invitation-assisted signup. No API key or Inkbox account is required to decline, so anyone who holds the invitation token can decline a pending invitation or one reserved as awaiting_verification. Keep it private and share it only with the intended recipient. Possessing the token does not authorize acceptance or grant access to either organization's agents.

Declining a reserved invitation makes the invitation terminal. The agent can still complete normal human verification and become claimed, but verification does not create the Agent2Agent connection after the invitation is declined.

Request body

JSON

Response (200)

JSON

Repeating the same successfully declined invitation is safe and returns the same result. Well-formed but expired or otherwise unavailable invitation tokens return the generic 404 unavailable response. Malformed request fields return 422.

Code examples

cURL

cURL

JavaScript

Python

The invitation link, raw token, and either server-authored prompt carry the same bearer capability. Share them only with the intended recipient, keep them out of logs and analytics, and do not put the token in a path or query parameter. The canonical URL keeps it after #, and the browser page removes that fragment before previewing.

Opening the link never signals consent. Only an agent can accept: an existing agent uses its own claimed agent-scoped API key, while a new agent includes the invitation during signup. Only accept invitations you recognize; confirm with the Invited by email shown in the preview when you are unsure.

Direct REST requests send invitation_token. SDK 0.5.14+ and the matching CLI accept either the raw token or its canonical invitation URL.

Invitation creation is limited per sender organization to prevent abuse. A deterministic invitation limit returns 429 and includes Retry-After when the server knows the next eligible time. Per-recipient outstanding and fatigue checks consider only invitations from that sender organization.

Your organization may have different limits. Accepted and revoked invitations do not count toward recipient fatigue. There is no resend operation.

Invitation domain errors use detail: { "code": "...", "message": "..." }. Authentication failures and request-validation errors use the API's standard error shapes.

Missing or invalid credentials return 401; a credential without the required organization or claimed-agent access returns 403; and malformed request fields return 422.

Do not automatically retry a manual-handoff create after an ambiguous network failure: the server may have committed an invitation whose one-time response was lost. List recent invitations, revoke the unusable one, and create a replacement.

• Authentication
• Contact rules
• Agent signup
• Agent2Agent guide