IDClawserver API

API for AI agent identities backed by RODiT tokens on NEAR, including facial token_id encoding.

Version: 0.1.0

Skills

idclawserver Skills

This file describes high-level capabilities that can be exposed to AI agents via MCP.

• get_noncets
  Protected endpoint to obtain a strong random timestamp+noncets composite (NOT a simple nonce) for challenge–response protocols. Returns noncets, noncets_hex, and timestamp fields for constructing API.IDENTYCLAW.COM hello messages.
  HTTP: GET /api/noncets (requires Bearer authentication)

• lookup_identity_by_token
  Protected endpoint to fetch the public identity/persona for a given token_id, including parsed userselected_dn_info with contactUri, displayName, and name attributes.
  HTTP: GET /api/identity/token/{tokenId} (requires Bearer authentication)

• get_my_identity
  Protected endpoint returning the caller's own identity based on their authenticated RODiT token.
  HTTP: GET /api/me/identity

• verify_agent_identity
  Protected endpoint that verifies another agent's identity using off-band evidence and mutual authentication.
  HTTP: POST /api/identity/verify

• mint_client_rodit
  Public endpoint to request minting of a client RODiT token for a service provider via SignPortal, validating requested permissions and minting fee.
  HTTP: POST /api/signclient

• get_policies
  Public endpoints to retrieve service policies for compliance evaluation before becoming a customer. Available via RFC 8615 well-known URIs and MCP resources.
  HTTP: GET /.well-known/terms-of-service, GET /.well-known/privacy-policy, GET /.well-known/data-retention, GET /.well-known/idclaw-service
  MCP: policy:terms, policy:privacy, policy:data-retention, policy:service-info

• setup_near_account
  Onboarding guide for AI agents that need a NEAR implicit account before minting a RODiT token. Covers installing near-cli-rs, generating an Ed25519 keypair, deriving the implicit account address, and obtaining NEAR tokens (testnet faucets and mainnet exchanges).
  MCP: onboarding:near
  HTTP: GET /api/mcp/resource/onboarding:near

RODiT Token Metadata Capabilities

RODiT (Rich Online Digital Token) tokens on NEAR blockchain contain comprehensive metadata for API access control and identity representation. Understanding these capabilities helps agents leverage the full power of the identity system.

Distinguished Name (userselected_dn)

The userselected_dn field uses RFC 2253-style format with custom attributes for structured identity information:

Format: NNSWF=NameNotSharedWithFamily,NSWF=NameSharedWithFamily,ContactURI=scheme:authority:identifier,...

Supported Attributes:

| Attribute | Required | Description | Example | |-----------|----------|-------------|---------| | NNSWF | Yes | Name Not Shared With Family | Alice | | NSWF | No | Name Shared With Family | Smith | | ContactURI | No | Generic identifier | twitter:x.com:alice, email:gmail.com:alice | | taxRes | No | Tax residence country (ISO 3166-1 alpha-2) | US, GB, DE | | inceptDateTime | No | Incept date/time (GeneralizedTime) | 19900315120000Z | | inceptPlace | No | Incept place (Plus Code) | 9F4MGCH7+R6 | | taxPayer | No | Tax payer ID | 123-45-6789 | | address | No | Contact address (Plus Code) | 87G8Q23F+XF | | Creature | No | Descriptive label | Friendly Bot, AI Agent | | AvatarURL | No | Avatar media URL | https://example.com/avatar.png | | EmojiURL | No | Emoji asset URL | https://example.com/emoji.svg |

ContactURI Format: scheme:authority:identifier

• Twitter/X: twitter:x.com:username
• Email: email:gmail.com:user
• Telegram: telegram:telegram.com:username
• Phone: phone:ES:34683493049
• LinkedIn: linkedin:linkedin.com:userid
• GitHub: github:github.com:username

Examples:

# Minimal (required only)
NNSWF=Alice

# With contact info
NNSWF=John,NSWF=Smith,ContactURI=email:gmail.com:jsmith,taxRes=US

# AI Agent example
NNSWF=ClientApp,ContactURI=email:example.com:client,taxRes=US,Creature=Friendly Bot

Validation Rules:

• Maximum DN length: 1024 bytes
• Only NNSWF is required
• RFC 2253 special characters (, + " \ < > ; = #) must be escaped with backslash
• Unknown attributes allowed for extensibility

Facial Token ID Encoding

Each RODiT token_id is a 12-character lowercase ASCII string encoding facial features:

Format: 11 category indices + 1 checksum letter

Category Order (positions 0-10): 0. skin_tones (19 values: a-s)

1. regional_bone_structure (12 values: a-l)
2. face_shape (15 values: a-o)
3. age_related (5 values: a-e)
4. eyes (10 values: a-j)
5. eyebrow_style (6 values: a-f)
6. overall_structure (2 values: a-b for masculine/feminine)
7. nose (6 values: a-f)
8. lips (5 values: a-e)
9. skin_conditions (6 values: a-f)
10. hair_color (11 values: a-k)

Example Decoding:

• Token ID: aaaaaaaaaaaa
  • Skin tone: a = pale-skinned
  • Bone structure: a = Nordic
  • Face shape: a = oval-faced
  • Age: a = teenage-person
  • Eyes: a = small-eyes
  • Eyebrows: a = thick-eyebrows
  • Structure: a = masculine
  • Nose: a = aquiline-nose
  • Lips: a = thin-lips
  • Skin: a = freckled
  • Hair: a = black-hair
  • Checksum: a (validates sum of indices)

Checksum Calculation:

sum_indices = Σ(token_id[i] - 'a') for i in 0..10
checksum_index = sum_indices % 26
checksum_letter = 'a' + checksum_index

Token Metadata Fields

RODiT tokens contain comprehensive API access control metadata:

• openapijson_url: OpenAPI specification URL for the API
• not_after: Expiration date (ISO 8601 or 1970-01-01 for no limit)
• not_before: Start date (ISO 8601)
• max_requests: Request limit (numeric string, 0 = unlimited)
• maxrq_window: Time window for rate limits (seconds)
• webhook_url: Webhook endpoint for notifications
• webhook_cidr: IP restrictions for webhook
• allowed_cidr: Allowed IP ranges for API access
• allowed_iso3166list: JSON country policy, e.g., {"allow":["WLD"]}
• jwt_duration: JWT validity period in seconds (0 = unlimited)
• permissioned_routes: JSON describing entity/method permissions
• subjectuniqueidentifier_url: Stable identity descriptor URL
• serviceprovider_id: Issuing service identifier (format: bc=near.org;sc=contract.near;id=token_id)
• serviceprovider_signature: Issuer's signature over fee/issuance data

Token Profiles

Root RODiT (mint root):

• Environment: Private server/network
• Purpose: Top-level authority
• Defaults: No limits (not_after=1970-01-01, max_requests=0, jwt_duration=0)

Server RODiT (mint server):

• Environment: Private network
• Purpose: Server-side authorization for client token issuance
• Defaults: jwt_duration=3600, inherits serviceprovider_id from root

Client RODiT (mint client):

• Environment: Public Internet
• Purpose: End-client API consumer with actual routing and limits
• Defaults: Numeric max_requests, maxrq_window, jwt_duration=3600

API Endpoints for Metadata Access

• GET /api/identity/token/{tokenId}: Returns full token metadata including parsed userselected_dn_info with contactUri, displayName, and name attributes
• GET /api/identity/face/{tokenId}: Returns decoded facial features from token_id encoding
• GET /api/me/identity: Returns authenticated agent's own token metadata
• GET /api/me/face: Returns authenticated agent's own facial features

Endpoints

| Method | Path | Summary | Auth | | ------ | ---- | ------- | ---- | | GET | /.well-known/data-retention | Data Retention Policy | none | | GET | /.well-known/idclaw-service | Service Information | none | | GET | /.well-known/privacy-policy | Privacy Policy | none | | GET | /.well-known/terms-of-service | Terms of Service | none | | GET | /api/identity/face/{tokenId} | Get facial description for a peer token_id | Bearer | | GET | /api/identity/token/{tokenId} | Protected NEAR token lookup by token_id with parsed userselected_dn metadata | Bearer | | POST | /api/identity/verify | Verify a peer's hello using Ed25519 and a Morse-compatible canonical message | Bearer | | POST | /api/login | RODiT client login to obtain a JWT access token | none | | POST | /api/logout | RODiT client logout to invalidate the current session | Bearer | | GET | /api/mcp/resource/{uri} | Retrieve a specific MCP resource by URI | none | | GET | /api/mcp/resources | List available MCP resources (including OpenAPI schema) | none | | GET | /api/mcp/schema | Return the OpenAPI schema used by this server | none | | GET | /api/me/face | Get facial description for the authenticated agent's token_id | Bearer | | GET | /api/me/identity | Get NEAR token identity for the authenticated agent | Bearer | | GET | /api/metrics | Get current performance metrics for this IDClawserver instance | Bearer | | GET | /api/metrics/debug | Debug endpoint for metrics subsystem (admin only) | Bearer | | POST | /api/metrics/reset | Reset performance metrics counters (admin only) | Bearer | | GET | /api/metrics/system | Get system resource metrics (CPU, memory, etc.) | Bearer | | GET | /api/noncets | Get a concatenation-ready timestamp+noncets fragment for API.IDENTYCLAW.COM | Bearer | | POST | /api/sessions/cleanup | Cleanup expired sessions (admin) | Bearer | | GET | /api/sessions/list_all | List all active sessions (admin) | Bearer | | POST | /api/sessions/revoke | Revoke a specific session (admin) | Bearer | | POST | /api/signclient | Request minting of a client RODiT via SignPortal | none | | GET | /health | Health check | none | | GET | /swagger.json | Return the raw OpenAPI schema (this document) | none |