> ## Documentation Index
> Fetch the complete documentation index at: https://docs.versuno.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claim agent identity

> Attaches a real email address and password to an agent identity and sends a verification email. The account becomes permanent once the verification link  is opened by whoever controls the inbox (agent that has email access).


This endpoint is typically called by the claim page at `versuno.ai/claim/<token>`, not directly by the agent.

The `token` comes from the `claim_url` returned when the agent identity was created. It is single-use: after this call succeeds, the original `claim_url` is invalidated and replaced with an email-verification link.

<Note>The account becomes permanent only when the verification link in the email is opened. The agent needs access to the email inbox (via an email or MCP integration) to read and open it.</Note>


## OpenAPI

````yaml /openapi.yaml post /auth/claim-agent-identity
openapi: 3.1.0
info:
  title: Versuno Public API
  description: >
    The Versuno Public API lets you manage AI assets, projects, and version
    history programmatically.


    All endpoints except key management require a Bearer API key in the
    `Authorization` header.

    API keys are formatted as
    `uk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.
  version: 1.0.0
  contact:
    email: support@versuno.ai
servers:
  - url: https://versuno.ai/api/public
    description: Production
  - url: http://localhost:3000/api/public
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Verify API key validity and retrieve the caller's identity.
  - name: Teams
    description: Teams the authenticated user owns or is an active member of.
  - name: Assets
    description: AI assets — prompts, personas, contexts, system prompts, and skills.
  - name: Asset Trash
    description: Single-asset soft-delete, restore, and permanent delete lifecycle.
  - name: Bulk Asset Trash
    description: Bulk trash operations across multiple assets at once.
  - name: Projects
    description: Project folders for organising assets and teams.
  - name: Project Trash
    description: Project trash lifecycle — trashing deletes the entire subtree.
  - name: Versioning
    description: Full-snapshot version history with non-destructive revert support.
  - name: Public Brains
    description: >-
      Graph-based knowledge structures composed of containers (folders/groups)
      and nodes (content items). Read the graph, or run semantic RAG queries
      against it.
  - name: Memory
    description: >-
      The universal agent-memory layer. Capture coding-agent memory, recall it
      semantically, and resolve contradictions. Capture-only, scoped to your API
      key's account.
  - name: Key Management
    description: >-
      Create, update, and delete API keys. These endpoints do not require a
      Bearer token.
paths:
  /auth/claim-agent-identity:
    post:
      tags:
        - Authentication
      summary: Claim agent identity
      description: >
        Attaches a real email address and password to an agent identity and
        sends a verification email. The account becomes permanent once the
        verification link  is opened by whoever controls the inbox (agent that
        has email access).
      operationId: claimAgentIdentity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - token
                - email
                - password
              properties:
                token:
                  type: string
                  description: Claim token from the `claim_url` path.
                  example: abc123def456...
                email:
                  type: string
                  format: email
                  description: A real email address the agent (or its human) can access.
                  example: you@example.com
                password:
                  type: string
                  minLength: 8
                  description: Password for the account. Minimum 8 characters.
                  example: yourpassword
            example:
              token: abc123def456...
              email: you@example.com
              password: yourpassword
      responses:
        '200':
          description: >-
            Verification email sent. The agent opens the verification link from
            the inbox to make the account permanent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: verification_sent
                  message:
                    type: string
                    example: >-
                      We sent a confirmation link to you@example.com. Click it
                      to finish claiming the account.
              example:
                status: verification_sent
                message: >-
                  We sent a confirmation link to you@example.com. Click it to
                  finish claiming the account.
        '400':
          description: Claim token invalid, expired, or already used.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '409':
          description: Email is already attached to another Versuno account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: >-
                      That email is already associated with a different account.
                      Please use a different email.
        '422':
          description: >-
            Validation failed — email format invalid, password too short, or
            missing fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '502':
          description: Verification email failed to send — try again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Could not send the verification email. Please try again.
      security: []
      servers:
        - url: https://versuno.ai/api
          description: Production (auth namespace)
        - url: http://localhost:3000/api
          description: Local development (auth namespace)
components:
  schemas:
    Error400:
      type: object
      properties:
        error:
          type: string
          example: 'Wrong data: assetType is required'
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Versuno API key. Must be prefixed with `Bearer`. Format: `Bearer
        uk_live_...`
      x-default: Bearer uk_live_your_api_key_here

````