Registration Flow

Detailed explanation of how agent registration works, from initiation to approval.

Overview

The registration flow has three parties:

1. AI Agent - Initiates registration via API
2. Human Operator - Receives email and approves
3. SupportRetriever - Processes and creates account

Step-by-Step Flow

1. Agent Initiates Registration

Endpoint: POST /api/agent/register

Request:

{
  "operator_email": "human@company.com",
  "agent_name": "Cursor AI",
  "agent_version": "1.0",
  "purpose": "Setting up support form for new project"
}

What Happens:

• Email format validation
• Disposable email check
• Rate limiting check (per-email, per-IP, global)
• Verification token generated
• Registration record created in database
• Verification email sent to operator

Response:

{
  "registration_id": "abc-123-def-456",
  "status": "pending_verification",
  "message": "If this email exists, a verification email has been sent."
}

Important: The response format is identical regardless of whether the email exists (prevents email enumeration).

2. Human Operator Receives Email

The operator receives an email with:

• Agent name and version
• Purpose stated by agent
• Warning: "We cannot verify this agent's identity"
• Approve / Decline / Report buttons

Email Subject: "An AI agent wants to set up customer support for you"

3. Human Clicks Approve

Opens /agent-verify?token=xxx which shows:

For New Users:

• Password creation form
• Terms of Service checkbox
• Turnstile verification
• "Approve & Create Account" button

For Existing Users:

• Shows what agent can/cannot do
• Turnstile verification
• "Approve Access" button (no password needed)

4. Account Created

What Happens Behind the Scenes:

• User account created (if new) or linked (if existing)
• Default form created automatically
• API key generated
• Registration marked as "approved"
• API key stored temporarily for agent retrieval

5. Agent Polls Status

Endpoint: GET /api/agent/status?registration_id=xxx

While Pending:

{
  "status": "pending_verification",
  "message": "Waiting for operator approval"
}

When Approved:

{
  "status": "approved",
  "api_key": "sr_live_abc123...",
  "form_url": "https://supportretriever.com/form/uuid",
  "form_id": "uuid",
  "message": "Registration approved. Store this API key securely - it will not be shown again."
}

Important: The API key is returned only once. Store it securely immediately.

Rate Limiting

Registration requests are rate limited:

• Per Email: Max 1 request per 24 hours
• Per IP: Max 5 requests per hour
• Global: Max 100 requests per hour

If rate limited, you'll receive a 429 status with error message.

Token Expiry

Verification tokens expire after 24 hours. If the operator doesn't approve within 24 hours:

• Token becomes invalid
• Registration status changes to "expired"
• Agent receives "expired" status on poll

Status Values

Error Handling

Invalid Email Format

{
  "error": "Invalid email format"
}

Disposable Email

{
  "error": "Disposable email addresses are not allowed"
}

Rate Limit Exceeded

{
  "error": "Rate limit exceeded: max 1 request per email per 24 hours"
}

Registration Not Found

{
  "error": "Registration not found"
}

Security Features

• Email Enumeration Prevention: Same response format regardless of email existence
• Rate Limiting: Prevents abuse and email bombing
• Token Expiry: 24-hour window for approval
• Turnstile Verification: Bot protection on approval page
• One-Time API Key: Key shown only once, then cleared

Related Topics

• Getting Started
• Error Codes
• Form Customization