Manage access to private agents
Control who can call your private agent by sending and revoking invitations.
Overview
A public agent is callable by anyone on Blocks Network. A private agent is not listed in the catalog and rejects calls from anyone who has not been granted access.
Access to a private agent follows a three-step flow:
- The agent owner sends an invitation to an email address or organization slug.
- The invitee receives a token and accepts it with
blocks invite accept. - 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
Publish your agent with --listing private to restrict access to invited parties only.
blocks publish --listing privatePrivate agents do not appear in search or the Blocks Network catalog. Only parties with an active grant can call them. Use this setting while testing or when the agent is intended for a specific audience.
To change the listing posture later, re-run blocks publish with the new flag or update it from the Visibility tab on the agent detail page in the dashboard.
Invite someone
Send an invitation with blocks invite send. Provide either --email or --org — exactly one is required.
Invite by email address:
blocks invite send <agentName> --email user@example.comInvite an entire organization by slug:
blocks invite send <agentName> --org my-org-slugOn success:
Invitation sent to user@example.com
or
Invitation sent to org my-org-slug
--orgare mutually exclusive. Providing both in the same command is an error. Providing neither is also an error.
View pending invitations
List invitations that have been sent but not yet accepted.
blocks invite list <agentName>Output columns:
| Column | Description |
|---|---|
ID | Invitation identifier |
EMAIL | Email address the invitation was sent to |
SCOPE | Whether access was granted to an individual or an org |
CREATED | Timestamp when the invitation was created |
EXPIRES | Timestamp when the invitation expires if not accepted |
An invitation stays in the pending list until the invitee accepts it or it expires. Once accepted, it no longer appears here — it moves to the grants list instead.
Accept an invitation
This step is performed by the invitee, not the agent owner.
blocks invite accept <token>Replace <token> with the token provided by the agent owner. 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 — it is consumed on acceptance.
The token is delivered via the invitation mechanism — if you have not received one, ask the agent owner to send you an invitation.
View active grants
List parties who have accepted an invitation and currently have access.
blocks invite grants <agentName>Output columns:
| Column | Description |
|---|---|
ID | Grant identifier |
SCOPE | Whether the grant applies to an individual or an org |
GRANTEE | Email address or org slug that was granted access |
CREATED | Timestamp when the grant was created (invitation accepted) |
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.comRevoke access for an organization:
blocks invite revoke <agentName> --org my-org-slugOn success:
Access revoked for user@example.comor
Access revoked for my-org-slugRevocation takes effect immediately. Subsequent calls from the revoked party are rejected. To restore access, send a new invitation.
--orgare 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.