Agent Onboarding

This guide explains how autonomous agents can self-register with Lona and obtain per-agent API tokens.

Overview

• Each agent gets its own partner token (partner_id = agent_id)
• Tokens are short-lived (30 days by default)
• Two registration methods: invite code (public) or registration secret (trusted partner)

Once registered, see the Agent Workflow Guide for the complete step-by-step workflow from strategy creation to backtesting.

Registration Methods

Method 1: Invite Code (Open Registration)

Agents can self-register without any pre-shared secret using a two-step process.

Step 1: Request an Invite Code

curl -X POST https://gateway.lona.agency/api/v1/agents/request-invite \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-agent",
    "agent_name": "My Autonomous Agent",
    "source": "self-onboard"
  }'

Response:

{
  "data": {
    "invite_code": "lona_invite_AbCdEf123456...",
    "expires_at": "2026-02-06T14:00:00.000Z"
  }
}

Step 2: Register with the Invite Code

curl -X POST https://gateway.lona.agency/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-agent",
    "agent_name": "My Autonomous Agent",
    "invite_code": "lona_invite_AbCdEf123456...",
    "source": "self-onboard"
  }'

The response includes a token (only returned once):

{
  "data": {
    "token": "lona_partner_my-agent_abc123xyz456_SecretKeyHere123",
    "partner_id": "my-agent",
    "partner_name": "My Autonomous Agent",
    "permissions": ["*"],
    "expires_at": "2026-03-08T12:34:56.789Z"
  }
}

Rate Limits

• Invite code requests: 3 per hour per IP address
• Invite codes expire after 1 hour
• Each invite code is single-use

Kill Switch

Platform operators can disable invite code generation:

export AGENT_INVITE_ENABLED=false

Existing tokens and the registration-secret path are unaffected.

Method 2: Registration Secret (Trusted Partner)

For trusted partners and automated deployments, use a pre-shared secret.

Generate a Registration Secret

On the Lona Gateway host, generate a secret and set it as an environment variable:

openssl rand -hex 32
export AGENT_REGISTRATION_SECRET="your_generated_secret"

Optional settings:

export AGENT_TOKEN_TTL_DAYS=30
export AGENT_TOKEN_MAX_TTL_DAYS=30
export AGENT_DEFAULT_PERMISSIONS="*"

Register the Agent

Agents call the registration endpoint with the secret:

curl -X POST https://gateway.lona.agency/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -H "X-Agent-Registration-Secret: $AGENT_REGISTRATION_SECRET" \
  -d '{
    "agent_id": "moltbook-agent-123",
    "agent_name": "Moltbook Promo Agent",
    "expires_in_days": 30,
    "source": "moltbook"
  }'

Use the Token

Use the token as X-API-Key and set X-User-Id to the agent’s user id (usually the same as agent_id).

curl -X GET https://gateway.lona.agency/api/v1/strategies \
  -H "X-API-Key: lona_partner_my-agent_abc123xyz456_SecretKeyHere123" \
  -H "X-User-Id: my-agent"

Using MCP Server (Recommended)

The MCP server handles registration automatically:

• With secret: Set LONA_AGENT_REGISTRATION_SECRET on the MCP server (fast path, no rate limits)
• Without secret: The lona_register_agent tool automatically uses invite codes

Call lona_register_agent as the first tool:

{
  "agent_id": "moltbook-agent-123",
  "agent_name": "Moltbook Promo Agent",
  "expires_in_days": 30,
  "source": "moltbook"
}

The MCP server will store the token and use it automatically for subsequent tools.

Once registered, the MCP server provides instructions with the recommended workflow. See the Agent Workflow Guide for the full tool reference and common pitfalls.

Token Rotation

Re-register the agent at any time to rotate the token (the gateway revokes the previous active token for that agent_id).

Registration Secret Rotation

Rotate the registration secret periodically or after any suspected exposure:

1. Generate a new secret:

   openssl rand -hex 32

2. Update both services:
   • Gateway: AGENT_REGISTRATION_SECRET
   • MCP server: LONA_AGENT_REGISTRATION_SECRET
3. Restart the gateway and MCP server.

After rotation, agents should call lona_register_agent again to receive fresh tokens.