# 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://oauth.koompi.org
SDK: npm install @koompi/oauth
Dashboard: https://dash.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://oauth.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://oauth.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..."
  }
}
```

### Step 3: Get User Info (Optional - if you need to refresh user data)
```http
GET https://oauth.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://oauth.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

| 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.

---

## 4. ERC20 API (Token Operations)

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

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

### Transfer Tokens (Requires wallet.transfer scope)
```http
POST https://oauth.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://oauth.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://oauth.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 @koompi/oauth
```

### Frontend (Browser)
```typescript
import { KoompiAuth } from "@koompi/oauth";

const auth = new KoompiAuth({
  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 { KoompiAuth } from "@koompi/oauth";

const auth = new KoompiAuth({
  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 |
|----------|--------|------|---------|
| /v2/oauth | GET | None | Start KID flow (redirect) |
| /v2/oauth/token | POST | Credentials | Exchange code for tokens |
| /v2/oauth/refresh | POST | Credentials | Refresh access token |
| /v2/oauth/userinfo | GET | Bearer Token | Get user profile |
| /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. 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