terminal

UIID API v1

Universal Integrated Identity (UIID) provides a zero-trust, passwordless identity layer for the modern web. Built on sovereign identity principles.

01. Core Concepts

Core ID

The central anchor of a user's digital existence. Unique and permanent.

Aliases

Contextual sub-identities. Disposable and isolated per application context.

Immutable Nodes

Non-editable data anchors. These block account deletion until removed by the provider.

02. Authentication (OIDC)

hub

Enterprise ready

Keycloak & SAML Bridging

UIID is fully compatible with Keycloak Identity Brokering. Position UIID as your "Master IdP" to bridge identity into legacy SAML 2.0 environments, LDAP, or Active Directory.

check_circle Zero-Code Enterprise Integration

check_circle SAML 2.0 Bridge Support

check_circle B2B Multitenancy (Realms)

check_circle Corporate Identity Isolation

PUT /api/v1/aliases/{alias_id}/public-key

Public Key Registration

Registers or updates a client-generated Ed25519 public key (PEM, Base64URL, or Hex) for the specified alias.

curl -X PUT "https://uiid.linkspreed.com/api/v1/aliases/UIID-Alias-80BB.../public-key" \
     -H "Authorization: Bearer [TOKEN]" \
     -H "Content-Type: application/json" \
     -d '{"public_key": "", "algorithm": "Ed25519"}'

Response Example

{
  "status": "success",
  "message": "public_key_saved",
  "alias_id": "UIID-Alias-80BB...",
  "public_key": "",
  "algorithm": "Ed25519"
}

GET /oauth/authorize

Initiate Handshake

Redirect users to this endpoint to begin the UIID passwordless login flow. After successful auth, the user is sent back to your redirect_uri with a code.

Usage Example

https://uiid.linkspreed.com/oauth/authorize?
client_id=YOUR_CLIENT_ID&
redirect_uri=https://your-app.com/callback&
response_type=code&
scope=openid profile email alias:read:public

2. Token Exchange

Exchange the code from the redirect for a bearer_token.

JavaScript Integration

                const params = new URLSearchParams({
                grant_type: 'authorization_code',
                code: 'CODE_FROM_URL',
                client_id: 'YOUR_CLIENT_ID',
                client_secret: 'YOUR_CLIENT_SECRET',
                redirect_uri: 'YOUR_REDIRECT_URI'
                });

                const response = await fetch('https://uiid.linkspreed.com/oauth/token', {
                method: 'POST',
                body: params
                });
                const data = await response.json();

Expected Response

                {
                "access_token": "eyJhbGci...",
                "token_type": "Bearer",
                "expires_in": 3600,
                "refresh_token": "ref_987654321",
                "scope": "openid profile email"
                }

3. Token Refresh Flow

Access tokens are short-lived. Use the refresh_token to obtain a new one without re-authenticating the user.

cURL Refresh Request

                curl -X POST "https://uiid.linkspreed.com/oauth/token" \
                -d "grant_type=refresh_token" \
                -d "refresh_token=YOUR_REFRESH_TOKEN" \
                -d "client_id=YOUR_CLIENT_ID" \
                -d "client_secret=YOUR_CLIENT_SECRET"

New Token Payload

                {
                "access_token": "new_eyJhbGci...",
                "token_type": "Bearer",
                "expires_in": 3600,
                "refresh_token": "new_ref_...",
                "scope": "openid profile"
                }

GET /oauth/userinfo

Fetch User Claims

cURL Integration

curl -X GET "https://uiid.linkspreed.com/oauth/userinfo" \
     -H "Authorization: Bearer [ACCESS_TOKEN]"

Response Structure

{
  "sub": "did:uiid:9D1B-3239-5D1D-8399",
  "name": "Anonymous UIID User",
  "email": "[email protected]",
  "email_verified": true,
  "uiid_core_id": "did:uiid:9D1B-3239-5D1D-8399"
}

OIDC Discovery

GET /.well-known/openid-configuration

Automated configuration for OIDC clients (NextAuth, Passport, etc.)

JWKS JSON

GET /.well-known/jwks.json

Public keys to verify ID token signatures on your server.

02c. Model Context Protocol (MCP) Server

MCP Protocol Live

AI Assistant & LLM Agent Integration

UIID implements the Anthropic Model Context Protocol (MCP) spec over HTTP POST (/mcp) and Server-Sent Events SSE (/mcp/sse). AI tools like Google Gemini, Anthropic Claude, and autonomous agents can securely query your sovereign identity, manage aliases, and spawn agent UIIDs.

POST /mcp

JSON-RPC 2.0 Endpoint

Handles JSON-RPC 2.0 requests for initialize, tools/list, tools/call, prompts/get, and resources/read.

Sample Request (tools/call)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_user_profile",
    "arguments": {}
  }
}

Response (200 OK)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"uiid_core_id\": \"did:uiid:9D1B-5D1D-4C9A\",\n  \"email\": \"[email protected]\",\n  \"trust_score\": 85\n}"
      }
    ]
  }
}

GET / POST /mcp/sse & /mcp/messages

SSE Streaming Transport

Establish a real-time event stream via GET /mcp/sse. The server emits an initial event: endpoint containing /mcp/messages?sessionId=... for submitting JSON-RPC messages.

02b. WebAuthn / Passkey Provider API

Passkey As A Service

Outsourced WebAuthn Engine

UIID acts as a full WebAuthn Relying Party (RP) provider for external applications. Delegate passkey creation, challenge generation, and cryptographic assertion verification directly to UIID without complex server cryptography.

POST /api/v1/passkey-provider/register/begin

Begin Passkey Creation

Initiates passkey creation options for an external application user.

Request Body (JSON)

{
  "client_id": "pk_app_...",
  "client_secret": "sk_app_...",
  "external_user_id": "usr_98765",
  "external_user_name": "[email protected]"
}

Response (200 OK)

{
  "session_id": "dev_reg_...",
  "options": {
    "publicKey": {
      "rp": { "name": "Your App", "id": "yourapp.com" },
      "user": { "id": "...", "name": "[email protected]" },
      "challenge": "..."
    }
  }
}

POST /api/v1/passkey-provider/register/finish

Verify & Store Passkey

Validates browser WebAuthn attestation response and registers passkey.

Request Body (JSON)

{
  "client_id": "pk_app_...",
  "session_id": "dev_reg_...",
  "external_user_id": "usr_98765",
  "external_user_name": "[email protected]",
  "credential": { /* browser navigator.credentials.create() result */ }
}

Response (200 OK)

{
  "status": "success",
  "passkey": {
    "id": "...",
    "external_user_id": "usr_98765",
    "created_at": "2025-05-15T12:00:00Z"
  }
}

POST /api/v1/passkey-provider/authenticate/*

Passkey Authentication

Perform passkey assertion verification for external users. Send /authenticate/begin with external_user_id to receive assertion options, then call /authenticate/finish with the signed credential.

03. App Management

POST /api/v1/applications

Onboard Application

JavaScript Implementation

await fetch('https://uiid.linkspreed.com/api/v1/applications', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer [TOKEN]',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "name": "My New App",
    "redirect_uri": "https://myapp.com/callback"
  })
});

Expected Response

{
  "status": "success",
  "client_id": "app_550e8400-e29b...",
  "client_secret": "sec_f47ac10b..."
}

DELETE /api/v1/applications/{id}

Revoke Access

cURL Integration

curl -X DELETE "https://uiid.linkspreed.com/api/v1/applications/app_123" \
     -H "Authorization: Bearer [TOKEN]"

POST /api/v1/aliases/{id}/export

Export Alias Credential

Downloads an AES-256-GCM encrypted and HMAC-signed .uiid credential container for an individual sub-identity alias.

curl -X POST "https://uiid.linkspreed.com/api/v1/aliases/UIID-Alias-80BB.../export" \
     -H "Authorization: Bearer [TOKEN]" \
     -H "Content-Type: application/json" \
     -d '{"passphrase": "YourSecretPassword123"}'

Encrypted Alias Output

{
  "encrypted": true,
  "file_type": "uiid_alias_credential",
  "version": "2.0",
  "kdf": "pbkdf2-sha256",
  "salt": "dGVzdF9zYWx0...",
  "nonce": "bm9uY2Vf...",
  "ciphertext": "ZW5jcnlwdGVkX2FsaWFz...",
  "signature": "7d9a1c..."
}

04. Core ID API

GET /api/v1/core/uiid/generate

Public Utility

Generates a cryptographically unique UIID string for new registration onboarding.

{ "uiid": "did:uiid:80BB-59CE-1B90-4427" }

GET /api/v1/core/kyc/status

Identity Trust

Verification Levels

unverified (Basic)
pending (In Review)
verified (Trust Level 1+)

{
  "kyc_status": "verified",
  "trust_score": 85,
  "last_audit": "2026-01-15"
}

POST /api/v1/core/data

Encrypted Storage

Securely store encrypted application-specific settings directly on the user's Core ID.

// Request Body: 
{ 
  "key": "app_config", 
  "value": "...", 
  "is_public": false,
  "is_immutable": true // Optional: Requires storage:immutable scope
}

{ "status": "success", "message": "Identity node updated." }

GET /api/v1/core/applications

Auth Audit

Retrieve a list of all third-party applications currently authorized to access this Core ID.

{
  "status": "success",
  "applications": [
    { "id": 1, "name": "Linkspreed App", "client_id": "d2e19987...", "created_at": "..." }
  ]
}

POST /api/v1/core/uiid/export

Export Credential

Downloads an AES-256-GCM encrypted and HMAC-signed .uiid credential payload for the authenticated Core ID.

curl -X POST "https://uiid.linkspreed.com/api/v1/core/uiid/export" \
     -H "Authorization: Bearer [TOKEN]" \
     -H "Content-Type: application/json" \
     -d '{"passphrase": "YourSecretPassword123"}'

Encrypted Container Output

{
  "encrypted": true,
  "file_type": "uiid_core_credential",
  "version": "2.0",
  "kdf": "pbkdf2-sha256",
  "salt": "dGVzdF9zYWx0...",
  "nonce": "bm9uY2Vf...",
  "ciphertext": "ZW5jcnlwdGVkX2RhdGE...",
  "signature": "8f3b2a..."
}

05. Alias Network

GET /api/v1/aliases

Registry Query

Implementation (Fetch)

const res = await fetch('https://uiid.linkspreed.com/api/v1/aliases', {
  headers: { 'Authorization': 'Bearer [TOKEN]' }
});
const data = await res.json();

Expected Response

{
  "status": "success",
  "aliases": [
    { 
      "alias_id_str": "UIID-Alias-80BB...", 
      "alias_name": "Work Identity",
      "status": "active"
    }
  ]
}

POST /api/v1/aliases/create

Spawn Identity

Creates a new sub-identity for a specific app context. Requires user permission.

// Request Body: { "name": "Linkspreed Profile" }
{ 
  "status": "success", 
  "alias": { "alias_id_str": "UIID-Alias-...", "alias_name": "Linkspreed Profile" } 
}

PUT /api/v1/aliases/{id}/status

Status Control

Manage the lifecycle of an alias. Use this to pause activity, archive data, or lock the identity with a custom key.

// Body: { "status": "paused" } | { "status": "archived" } | { "status": "locked", "key": "YOUR_SECRET" }
{ 
  "status": "success", 
  "message": "Alias status updated successfully.",
  "new_status": "paused"
}

GET /api/v1/aliases/data/{id}

Hierarchical Retrieval

Fetches all data nodes for an alias and automatically reconstructs them into a nested JSON object.

curl -X GET "https://uiid.linkspreed.com/api/v1/aliases/data/UIID-Alias-..." \
     -H "Authorization: Bearer [TOKEN]"

Structured Response

{
  "status": "success",
  "data": {
    "profile": { "name": "Amy", "theme": "dark" },
    "settings": { "notifications": "enabled" }
  }
}

POST /api/v1/aliases/data

Full Overwrite

Replaces the entire data store for an alias with the provided JSON object. Use with caution.

// Body: { "alias_id": "...", "data": { "key1": "val1", "settings": { "theme": "cyber" } } }
{ "status": "success", "message": "Alias data updated successfully." }

PATCH /api/v1/aliases/data

Partial Update

Integration (Dot-Notation)

// Partially modify the data store
await fetch('https://uiid.linkspreed.com/api/v1/aliases/data', {
  method: 'PATCH',
  headers: { 'Authorization': 'Bearer [TOKEN]' },
  body: JSON.stringify({
    "alias_id": "UIID-Alias-...",
    "profile.theme": "dark",
    "is_encrypted": true,
    "is_public": false,
    "is_immutable": true // Release requires Request Deletion
  })
});

"Immutable nodes cannot be modified once set. Setting is_immutable: true locks the specific key-value pair."

POST /api/v1/aliases/storage/request-deletion

User Request

Users can trigger this to notify application providers that they wish to delete an immutable node.

// Request Body: { "alias_id": "...", "key": "membership_id" }
{ "status": "success", "message": "Deletion requested. The provider has been notified." }

DELETE /api/v1/aliases/data

Key Removal

// Body: { "alias_id": "...", "key": "profile.temporary_token" }
{ "status": "success", "message": "Key removed from alias store." }

DELETE /api/v1/aliases/{id}

Permanent Purge

Purges the identity and all its data nodes from the network.

curl -X DELETE "https://uiid.linkspreed.com/api/v1/aliases/UIID-Alias-80BB..." \
     -H "Authorization: Bearer [TOKEN]"

New: Alias Challenges & Public Keys

GET /api/v1/aliases/{alias_id}/public-key

Public Key Retrieval

Retrieves or auto-generates the Ed25519 public key associated with the specified alias.

curl -X GET "https://uiid.linkspreed.com/api/v1/aliases/UIID-Alias-80BB.../public-key" \
     -H "Authorization: Bearer [TOKEN]"

Response Example

{
  "status": "success",
  "alias_id": "UIID-Alias-80BB...",
  "public_key": "-----BEGIN PUBLIC KEY-----\nMCowKO...",
  "algorithm": "Ed25519"
}

POST /api/v1/aliases/{alias_id}/challenges

Generate Challenge

Generates a unique, short-lived (5-minute window) authentication challenge for the specified alias.

curl -X POST "https://uiid.linkspreed.com/api/v1/aliases/UIID-Alias-80BB.../challenges" \
     -H "Authorization: Bearer [TOKEN]"

Response Example

{
  "status": "success",
  "alias_id": "UIID-Alias-80BB...",
  "challenge_id": "CHL-a1b2c3d4",
  "challenge": "8f3e9a1b2c4d5e6f...",
  "expires_at": "2025-05-10T12:05:00Z"
}

GET /api/v1/aliases/{alias_id}/challenges/{challenge_id}

Challenge Lifecycle Query

Retrieves the current status (pending, verified, or expired) and timestamp of an issued challenge.

curl -X GET "https://uiid.linkspreed.com/api/v1/aliases/UIID-Alias-80BB.../challenges/CHL-a1b2c3d4" \
     -H "Authorization: Bearer [TOKEN]"

Response Example

{
  "status": "success",
  "alias_id": "UIID-Alias-80BB...",
  "challenge_id": "CHL-a1b2c3d4",
  "challenge_status": "pending",
  "expires_at": "2025-05-10T12:05:00Z"
}

POST /api/v1/aliases/{alias_id}/challenges/{challenge_id}/verify

Signature Verification

Verifies that the challenge was signed by the client private key corresponding to the specified alias's public key (supports Base64URL, Base64, or Hex signatures). Automatically consumes the challenge to enforce single-use replay protection.

curl -X POST "https://uiid.linkspreed.com/api/v1/aliases/UIID-Alias-80BB.../challenges/CHL-a1b2c3d4/verify" \
     -H "Authorization: Bearer [TOKEN]" \
     -H "Content-Type: application/json" \
     -d '{"signature": ""}'

Response Example

{
  "status": "success",
  "valid": true,
  "alias_id": "UIID-Alias-80BB...",
  "challenge_id": "CHL-a1b2c3d4",
  "verified_at": "2025-05-10T12:02:15Z"
}

New in v2.6

Shared Buckets & Collaboration

POST /api/v1/aliases/members

Collaborative Access

Adds another UIID to a specific data bucket. This enables real-time data exchange between different identities in the same alias context.

// Request Body: 
{ 
  "alias_id_str": "UIID-Alias-...", 
  "target_uiid": "did:uiid:80BB-...",
  "role": "chat_partner" 
}

GET /api/v1/aliases/members/{alias_id}

Member Registry

// Response:
{
  "status": "success",
  "members": [
    { "uiid": "did:uiid:...", "role": "owner", "added_at": "..." },
    { "uiid": "did:uiid:...", "role": "chat_partner", "added_at": "..." }
  ]
}

06. Ecosystem & Trust

GET /api/v1/marketplace/apps

App Discovery

Discover other UIID-enabled applications to build cross-platform integrations.

// Response:
{
  "status": "success",
  "apps": [
    { "id": 1, "name": "Linkspreed", "url": "https://linkspreed.com", "category": "Social" }
  ]
}

GET /api/v1/marketplace/apps/{id}

Specific App Insight

Fetch detailed metadata, category info, and rating stats for a specific marketplace application.

{
  "status": "success",
  "app": { "id": 1, "name": "Linkspreed", "description": "Next-Gen Social Network", ... }
}

GET /api/v1/badges

Badge Registry

Retrieve a list of all available badges in the UIID ecosystem that users can apply for or earn.

{
  "status": "success",
  "badges": [
    { "id": 1, "badge_name": "KYC Verified", "badge_key": "kyc_verified", "description": "Official Identity Verification" }
  ]
}

GET /api/v1/user/badges

Credential Verification

Retrieve all trust badges currently verified and owned by the authenticated user.

{
  "status": "success",
  "badges": [
    { "badge_key": "kyc_verified", "level": 1, "issued_at": "..." }
  ]
}

07. Auditing

GET /api/v1/audit/core

Full transaction history of the primary identity anchor.

// Returns:
{
  "audit_logs": [
    { "action": "LOGIN", "timestamp": "..." }
  ]
}

GET /api/v1/audit/alias

Action history for a specific identity context (requires alias_id).

// GET /api/v1/audit/alias?alias_id=...
{ "status": "success", "logs": [...] }

08. Local Integration

GET /api/v1/auth/check

Silent Detection

Used by "Smart Tags" to detect if a user is currently logged into the UIID Provider without forcing a redirect. Requires CORS with credentials.

Detection Logic

const session = await fetch('https://uiid.linkspreed.com/api/v1/auth/check', {
  credentials: 'include' // CRITICAL: Sends HttpOnly cookies
}).then(r => r.json());

if (session.logged_in) {
  console.log("Welcome back, " + session.uiid);
}

Response Schema

{
  "logged_in": true,
  "uiid": "did:uiid:80BB-59CE..."
}

JS Full Smart-Tag Implementation

Recognize returning users or create a temporary, cache-based identity for new users that can be converted to a full account later without losing local history.

(function() {
    const UIID_BASE = 'https://uiid.linkspreed.com';
    
    async function initSmartTag() {
        // 1. Check for global session
        const session = await fetch(`${UIID_BASE}/api/v1/auth/check`, { 
            credentials: 'include' 
        }).then(r => r.json());

        if (session.logged_in) {
            handleAuthenticatedUser(session.uiid);
        } else {
            handleAnonymousUser();
        }
    }

    async function handleAnonymousUser() {
        let tempId = localStorage.getItem('uiid_temp_id');
        
        if (!tempId) {
            // 2. Generate temporary ID if none exists
            const data = await fetch(`${UIID_BASE}/api/v1/core/uiid/generate`).then(r => r.json());
            tempId = data.uiid;
            localStorage.setItem('uiid_temp_id', tempId);
        }
        
        console.log("Tracking anonymous data for ID:", tempId);
        
        // 3. Prompt for conversion after 2 minutes or interaction
        setTimeout(() => {
            if (confirm("Claim your temporary UIID to secure your data?")) {
                window.location.href = `${UIID_BASE}/register?temp_id=${tempId}`;
            }
        }, 120000);
    }

    initSmartTag();
})();

1. Detection

Checks global auth status via HttpOnly cookies and CORS.

2. Local Cache

Stores a "Temporary UIID" in localStorage for local state tracking.

3. Conversion

Passes temp_id to register flow to "claim" the identity.

4. Sync

Preserves all local data nodes when upgraded to a full account.

09. Technical Specs

Permission Scopes

Scope	Capability
openid, profile, email	Standard OIDC claims.
core:read:minimal	Access authorized app lists.
core:read:sensitive	Access KYC & trust score.
core:write	Modify Core KV store (MFA required).
alias:create	Create new identity contexts.
alias:read:public	Read public node data.
alias:read:private	Read private nodes (PIN may apply).
alias:write	Modify nodes or purge aliases.
storage:immutable	Create non-editable data nodes (2FA required).
audit:read	Access activity stream.

Error Handling

Standard HTTP codes apply. Payloads include a status and error key.

400: Invalid Request
401: Unauthorized
403: Forbidden (includes required_scope)
404: Not Found (JSON)

Operational Limits

Rate Limiting

100 requests / 60s per Token.

Pagination

Cursor-based via next_cursor field.

10. Webhooks (Real-Time)

POST /api/v1/webhooks

Subscribe to identity events. Returns a secret for signature verification.

{
  "url": "https://your-api.com/webhook",
  "events": ["alias.data.created", "alias.data.updated"],
  "alias_id": "UIID-Alias-..." // Optional
}

Available Events

alias.data.created: New node added.
alias.data.updated: Existing node modified.

security Signature Verification (HMAC-SHA256)

Every webhook request includes an X-UIID-Signature header.

// Node.js/Express Verification
const crypto = require('crypto');
const signature = req.headers['x-uiid-signature'];
const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
const digest = hmac.update(JSON.stringify(req.body)).digest('hex');

if (signature === digest) { /* Valid UIID Event */ }