Invite Codes

Invite codes let you onboard AI agents to your OpenTusk account in a single command. Instead of manually creating API keys, generating Sui keypairs, and linking addresses, you create a code and the agent redeems it — everything is set up automatically.

How it works

Owner                              Agent
  │                                  │
  ├─ Create invite code              │
  │  (dashboard or CLI)              │
  │                                  │
  ├─ Share code with agent ─────────►│
  │                                  ├─ opentusk login --invite-code <code>
  │                                  │    ├─ Generate Sui keypair (or use existing)
  │                                  │    ├─ Redeem code → get API key
  │                                  │    └─ Store API key + Sui key in config
  │                                  │
  ├─ Add agent to vault              │
  │  (by Sui address)                │
  │                                  ├─ Upload / download encrypted files
  │                                  │

The code is single-use and short-lived (default 1 hour). It creates an API key under your account with the agent’s Sui address bound. The agent’s Sui private key is generated locally and never leaves the agent’s machine.

Creating invite codes

Dashboard

Go to Settings → API Keys → Invite Agent. You can set:

• Key name — labels the API key created on redemption (e.g., “claude-code”, “cursor-agent”)
• Expiry — 1 hour (default), 4 hours, 24 hours, or 72 hours

CLI

# Basic — 1 hour expiry
opentusk invite create

# With a name and longer expiry
opentusk invite create --name "cursor-agent" --expires 24

# List your invite codes
opentusk invite list

# Revoke an unredeemed code
opentusk invite revoke <invite-code-id>

API

curl -X POST https://api.opentusk.ai/api/auth/invite-codes \
  -H "Authorization: Bearer otk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "expiresInHours": 4}'

Caution

The full invite code is only shown once at creation. The server stores a SHA-256 hash — the raw code cannot be retrieved later.

Redeeming an invite code

On the agent’s machine:

opentusk login --invite-code otinv_abc123...

This command:

1. Checks for an existing Sui key in config or OPENTUSK_SUI_PRIVATE_KEY env var
2. If none exists, generates a new Ed25519 keypair and stores it
3. Sends the invite code + Sui address to the API
4. Receives an API key (created under the owner’s account)
5. Stores the API key, Sui key, and bound address in config

After redemption, the agent is fully authenticated and ready to use the CLI, SDK, or MCP server.

Owner vs agent access

When an agent redeems an invite code, its API key has a different Sui address than the account owner. This automatically gives it agent-level access — it can work with files but cannot manage the account.

What agents can do

Operation	Allowed
Upload / download / list files	Yes
Create / list / rename / delete folders	Yes
List vaults and vault details	Yes
Soft-delete files (trash)	Yes
Restore / delete single trash items	Yes
List vault members	Yes
Read webhook details and delivery logs	Yes
Read account info	Yes

What only owners can do

Operation	Why restricted
Create / update / delete vaults	Structural changes
Create / revoke API keys	Security
Create / revoke invite codes	Security
Add / remove vault members	Access control
Link / unlink Sui address	Identity management
Change password	Security
Billing (checkout, plan changes, cancel)	Financial
Create / update / delete webhooks	Infrastructure
Empty all trash	Mass destructive

How access level is determined

Auth method	Condition	Access level
Web login (JWT)	—	Owner
API key, no Sui address	—	Owner
API key, Sui address matches account	Has owner’s key	Owner
API key, Sui address differs from account	Different key	Agent

The GET /api/account endpoint returns accessLevel: "owner" or "agent" so clients can adapt their UI.

Sui key locking

When an agent logs in via invite code, its Sui key is locked to its API key:

• opentusk sui setup and opentusk account setup-sui are blocked
• opentusk sui clear and opentusk account clear-sui are blocked
• The bound Sui address is checked locally on every operation

To change an agent’s Sui key, the owner must revoke the old API key and issue a new invite code.

Multiple agents

You can create multiple invite codes for multiple agents. Each agent gets its own API key and Sui keypair. Multiple API keys can share the same Sui address if needed (e.g., multiple agents using the same keypair).

To give multiple agents access to the same shared vault, add each agent’s Sui address as a vault member.

Managing agents

Viewing agent keys

Agent-created API keys appear in Settings → API Keys alongside manually created keys. They show the agent’s Sui address and the key name from the invite code.

Revoking agent access

To revoke an agent’s access:

1. Revoke its API key in Settings → API Keys (stops API access immediately)
2. Remove it from vault members if it had shared vault access (revokes decryption ability)

Adding agents to vaults

In the Add Member dialog on any shared vault, you’ll see a “Your Agents” dropdown listing all API keys with Sui addresses. Select an agent to add its address as a vault member — no need to copy-paste addresses.

Authentication All authentication methods: API keys, JWTs, OAuth.

MCP tools reference All 34 MCP tools available to agents.

Shared vaults Multi-agent encrypted file sharing.