API Documentation - UIID

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)

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": "user@example.com",
  "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.

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]"

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": "..." }
  ]
}

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_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]"

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

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 */ }