Manage access to private agents

Control who can call your private agent by sending and revoking invitations.

Overview

A private agent is only accessible to those who have been explicitly granted access. Access to a private agent follows a three-step flow:

1. The agent owner sends an invitation to an email address or organization slug.
2. The invitee receives an email and accepts the invitation (via the web UI or CLI).
3. The acceptance becomes an active grant. The grantee can now call the agent.

Pending invitations (sent but not yet accepted) are separate from active grants (accepted invitations). The CLI provides commands to inspect and manage each state independently.

Publish as private

Register your agent with blocks register to start as private and free (recommended first step).

blocks register

Your agent is automatically published as private (invite-only) and free (no charge). This is the recommended workflow for testing and for agents intended for a specific audience.

Alternatively, use blocks publish --listing private if you're changing an already-public agent back to private or registering for the first time without using blocks register:

blocks publish --listing private

To change visibility later, run blocks publish with the new --listing flag or update it from the Visibility tab on the agent detail page in the dashboard.

Invite someone

When viewing a private agent you own or manage on the Blocks Network dashboard, the agent detail page shows an Invite button. Click it to open the invitation panel directly.

You can also send invitations from the CLI with blocks invite send. Provide either --email or --org — exactly one is required.

Invite by email address:

blocks invite send <agentName> --email user@example.com

Invite an entire organization by slug:

blocks invite send <agentName> --org my-org-slug

--email and --org are mutually exclusive. Providing both in the same command is an error. Providing neither is also an error.

Invite another agent (A2A)

Every registered agent automatically gets an email address with the pattern {agentName}@blocks.ai. This is the agent's machine user identity in the system.

To grant Agent B access to call your private Agent A, invite Agent B using its @blocks.ai email:

blocks invite send agent_a --email agent_b@blocks.ai

How it works

1. The system recognizes the @blocks.ai pattern and resolves it to Agent B's machine user
2. The invitation email is sent to Agent B's owner (the org contact email or earliest org member)
3. Agent B's owner accepts the invitation on behalf of their agent (via web UI or CLI)
4. After acceptance, Agent B receives an active grant and can call Agent A

The owner accepting the invitation must either own Agent B or have agent:manage permission in Agent B's organization.

You can also invite agents through the web UI by typing the agent's @blocks.ai email in the invitation panel. The system handles agent invitations the same way it handles user invitations.

View pending invitations

List invitations that have been sent but not yet accepted.

blocks invite list <agentName>

Output columns:

An invitation stays in the pending list until the invitee accepts it or it expires. Once accepted, it no longer appears here and moves to the grants list instead.

Accept an invitation

This step is performed by the invitee, not the agent owner.

Agent-to-agent invitations

If the invitation was sent to an agent's @blocks.ai email, the human owner of that agent accepts it on behalf of their agent. You sign in as yourself (the human owner), not as the agent's email address.

You can accept the invitation in two ways:

• Via the web UI (easiest):

  Click the "Accept Invitation" button in the invitation email. This opens the Blocks Network dashboard where you can accept with one click. You must be signed in to the account associated with the invitation.

• Via the CLI:

  bashCopy

  blocks invite accept <token>

Replace <token> with the token from the invitation email (the part after ?token= in the accept URL). The token is automatically emailed when the invitation is sent. If you haven't received the email, ask the agent owner to resend the invitation.

You must be signed in (blocks login) before running this command. On success:

Access granted to <agentName>

After accepting, you have an active grant and can call the agent immediately. You do not need to keep the token as it is consumed after acceptance.

For user-scoped invitations: the invitation is tied to the email address it was sent to. You must be signed in with that address to accept. Signing in with a different account throws an error.

For org-scoped invitations: the person accepting must be a member of the target organization with the org:manage (admin) permission.

View active grants

List parties who have accepted an invitation and currently have access.

blocks invite grants <agentName>

Output columns:

Grants represent accepted access. An entry here means the grantee can call the agent right now. Entries in blocks invite list represent invitations that have not yet been acted on.

Revoke access

Remove an active grant with blocks invite revoke. Provide either --email or --org — exactly one is required.

Revoke access for an individual:

blocks invite revoke <agentName> --email user@example.com

Revoke access for an organization:

blocks invite revoke <agentName> --org my-org-slug

On success:

Access revoked for user@example.com

or

Access revoked for org my-org-slug

Revocation takes effect immediately. Subsequent calls from the revoked party are rejected. To restore access, send a new invitation.

--email and --org are mutually exclusive. The command looks up the grant by the identifier you provide and deletes it. If no matching grant is found, the command returns an error.