# KID (KOOMPI ID) API

> AI-native documentation for KID (KOOMPI ID) - a sovereign identification service with OAuth 2.0, blockchain wallet integration, and token management.

## Quick Reference

BASE_URL: https://api.kid.koompi.org
SDK: npm install @kid/oauth2
Dashboard: https://dash.kid.koompi.org

---

## 1. AUTHENTICATION TYPES

There are TWO ways to authenticate with KID APIs:

### OAuth Token (User Actions)
- For: User-authorized operations (transfers, profile access)
- Header: `Authorization: Bearer <access_token>`
- Scopes: profile.basic, wallet.transfer, wallet.balance

### API Key (Admin Actions)
- For: Project-level operations (NFT minting, admin transfers)
- Header: `X-API-Key: <client_secret>`
- No scopes needed

---

## 2. KID FLOW (Step by Step)

### Step 1: Redirect User to Login
```
GET https://api.kid.koompi.org/v2/oauth
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=profile.basic wallet.transfer
  &state=RANDOM_CSRF_TOKEN
```

### Step 2: Exchange Code for Tokens + User Info (Single Call)
```http
POST https://api.kid.koompi.org/v2/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "<code_from_callback>",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "https://yourapp.com/callback"
}
```

Response (includes user data):
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "...",
  "expires_in": 3600,
  "refresh_token_expires_in": 31536000,
  "scope": "profile.basic wallet.transfer",
  "user": {
    "_id": "...",
    "fullname": "John Doe",
    "email": "john@example.com",
    "wallet_address": "0x..."
  }
}
```

NOTE: If `openid` scope was requested, the response also includes an `id_token` (RS256-signed JWT). See Section 9 for OIDC details.
```

### Step 3: Get User Info (Optional - if you need to refresh user data)
```http
GET https://api.kid.koompi.org/v2/oauth/userinfo
Authorization: Bearer <access_token>
```

Response:
```json
{
  "user": {
    "_id": "...",
    "fullname": "John Doe",
    "email": "john@example.com",
    "wallet_address": "0x..."
  },
  "status": "success"
}
```

### Step 4: Refresh Token (When Access Token Expires)
```http
POST https://api.kid.koompi.org/v2/oauth/refresh
Content-Type: application/json

{
  "refresh_token": "<refresh_token>",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}
```

NOTE: Refresh tokens rotate - save the new refresh_token from response.

---

## 3. SCOPES

### Standard OAuth Scopes
| Scope | Data Access |
|-------|-------------|
| profile.basic | _id, fullname, username, avatar |
| profile.contact | email, phone, telegram_id |
| wallet.read | wallet_address |
| wallet.transfer | Allows ERC20 transfers on user's behalf |
| wallet.balance | Allows reading token balances |

Default scope is `profile.basic` if none specified.

### OpenID Connect (OIDC) Scopes
| Scope | Data Access |
|-------|-------------|
| openid | Enables OIDC mode (required for id_token) |
| profile | name, given_name, family_name, preferred_username, picture |
| email | email, email_verified |
| phone | phone_number, phone_number_verified |

NOTE: OIDC scopes (`openid`, `profile`, `email`, `phone`) can be combined with custom scopes (e.g., `openid profile email wallet.read`).

---

## 4. ERC20 API (Token Operations)

### Get Balance (Public - No Auth)
```http
POST https://api.kid.koompi.org/v2/erc20/balance
Content-Type: application/json

{
  "wallet_address": "0x...",
  "token_address": "0x..."
}
```

### Transfer Tokens (Requires wallet.transfer scope)
```http
POST https://api.kid.koompi.org/v2/erc20/transfer
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "to_address": "0x...",
  "token_address": "0x...",
  "amount": "1000000000000000000"
}
```

---

## 5. ERC1155 API (NFT Operations)

All NFT operations require API Key authentication.

### Mint NFT
```http
POST https://api.kid.koompi.org/v2/erc1155/mint
X-API-Key: <client_secret>
Content-Type: application/json

{
  "to_address": "0x...",
  "token_id": 1,
  "amount": 1
}
```

### Burn NFT
```http
POST https://api.kid.koompi.org/v2/erc1155/burn
X-API-Key: <client_secret>
Content-Type: application/json

{
  "from_address": "0x...",
  "token_id": 1,
  "amount": 1
}
```

---

## 6. SDK USAGE (TypeScript/JavaScript)

### Installation
```bash
npm install @kid/oauth2
```

### Frontend (Browser)
```typescript
import { KIDAuth } from "@kid/oauth2";

const auth = new KIDAuth({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
});

// Generate login URL with PKCE
const loginUrl = await auth.createLoginUrl({
  scope: ["profile.basic", "wallet.transfer"],
});

// Redirect to login
window.location.href = loginUrl;
```

### Backend (Node.js)
```typescript
import { KIDAuth } from "@kid/oauth2";

const auth = new KIDAuth({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
  redirectUri: "https://yourapp.com/callback",
});

// Exchange code for tokens
const tokens = await auth.exchangeCode({ code: "..." });

// Get user info
const user = await auth.getUserInfo(tokens.access_token);
```

---

## 7. ENDPOINTS SUMMARY

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| /.well-known/openid-configuration | GET | None | OIDC discovery document |
| /.well-known/jwks.json | GET | None | JSON Web Key Set (public keys) |
| /oauth | GET | None | Start KID flow (redirect) |
| /oauth/token | POST | Credentials | Exchange code for tokens (+id_token) |
| /oauth/refresh | POST | Credentials | Refresh access token |
| /oauth/userinfo | GET | Bearer Token | Get user profile (OIDC claims) |
| /v2/erc20/balance | POST | None | Get token balance |
| /v2/erc20/transfer | POST | Bearer Token | Transfer tokens (user) |
| /v2/erc1155/mint | POST | API Key | Mint NFT |
| /v2/erc1155/burn | POST | API Key | Burn NFT |

---

## 8. ERROR HANDLING

HTTP Errors:
- 400: Bad request (invalid parameters)
- 401: Unauthorized (invalid/expired token)
- 403: Forbidden (insufficient scope or invalid API key)
- 404: Not found

Error Response Format:
```json
{
  "error": "error_code",
  "error_description": "Human readable message"
}
```

Common Errors:
- `invalid_grant`: Invalid authorization code or refresh token
- `insufficient_scope`: Token lacks required scope
- `invalid_api_key`: Invalid or missing API key

---

## 9. OPENID CONNECT (OIDC) SUPPORT

KID is a standard-compliant OpenID Connect provider. This allows integration with Moodle, WordPress, Grafana, and any OIDC-compatible client.

### Discovery Endpoints
```
GET https://api.kid.koompi.org/.well-known/openid-configuration
GET https://api.kid.koompi.org/.well-known/jwks.json
```

### OIDC Authorization Flow

Step 1: Redirect user with `openid` scope
```
GET https://api.kid.koompi.org/oauth
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=openid profile email
  &state=RANDOM_CSRF_TOKEN
  &nonce=RANDOM_NONCE
  &response_type=code
```

Step 2: Exchange code for tokens (same as standard flow)
```http
POST https://api.kid.koompi.org/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "<code_from_callback>",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "https://yourapp.com/callback"
}
```

Response (includes `id_token` when `openid` scope is requested):
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email"
}
```

The `id_token` is an RS256-signed JWT containing standard OIDC claims:
- `iss` (issuer), `sub` (user ID), `aud` (client_id), `exp`, `iat`
- `nonce` (echoed back from authorization request)
- `at_hash` (access token hash)
- `name`, `given_name`, `family_name`, `preferred_username`, `picture` (with `profile` scope)
- `email`, `email_verified` (with `email` scope)
- `phone_number`, `phone_number_verified` (with `phone` scope)

Step 3: Userinfo returns OIDC-standard flat claims format
```http
GET https://api.kid.koompi.org/oauth/userinfo
Authorization: Bearer <access_token>
```

Response (when `openid` scope is present):
```json
{
  "sub": "507f1f77bcf86cd799439011",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "preferred_username": "johndoe",
  "email": "john@example.com",
  "email_verified": true,
  "picture": "https://storage.kid.koompi.org/avatars/..."
}
```

### Third-Party Integration (Moodle, WordPress, Grafana)

Use these settings in any OIDC client:
```
Discovery URL: https://api.kid.koompi.org/.well-known/openid-configuration
Client ID:     <from dashboard>
Client Secret:  <from dashboard>
Scopes:        openid profile email
```

---

## 10. SECURITY RULES

1. NEVER expose client_secret in frontend code
2. ALWAYS validate state parameter to prevent CSRF
3. Use HTTPS for all redirect URIs in production
4. Store refresh_token securely on server (httpOnly cookie)
5. Tokens expire: access_token = 1 hour, refresh_token = 1 year