# AIOZ Pin — API Keys

Base URL: https://api.aiozpin.network/api
Note: API key management requires JWT (Bearer token) authentication.

## Setup

```typescript
const BASE = 'https://api.aiozpin.network/api'
const JWT_HEADERS = {
  'Authorization': `Bearer ${process.env.AIOZ_PIN_JWT}`,
  'Content-Type': 'application/json'
}
```

---

## Generate API Key

POST https://api.aiozpin.network/api/apiKeys

Requires admin JWT. Record the secret immediately — it will not be accessible again.

```typescript
async function generateApiKey(name: string, isAdmin = false) {
  const body = isAdmin
    ? { name, scopes: { admin: true } }
    : {
        name,
        scopes: {
          admin: false,
          data: { pin_list: true, nft_list: true },
          pinning: { unpin: true, pin_by_hash: true, pin_file_to_ipfs: true },
          pin_nft: { unpin_nft: true, pin_nft_to_ipfs: true }
        }
      }

  const res = await fetch(`${BASE}/apiKeys`, {
    method: 'POST',
    headers: JWT_HEADERS,
    body: JSON.stringify(body)
  })
  return res.json()
}

const result = await generateApiKey('my-api-key')
// result.data.api_key   — store this as AIOZ_PIN_API_KEY
// result.data.secret_key — store this as AIOZ_PIN_SECRET_KEY (not shown again)
```

Response fields:
- data.name, data.api_key, data.secret_key

Scopes:
- admin: true — full access (sub-properties can be omitted)
- data.pin_list — list pins
- data.nft_list — list NFTs
- pinning.pin_file_to_ipfs — pin files
- pinning.pin_by_hash — pin by CID
- pinning.unpin — remove pins
- pin_nft.pin_nft_to_ipfs — create NFTs
- pin_nft.unpin_nft — remove NFTs

---

## List API Keys

GET https://api.aiozpin.network/api/apiKeys/list

```typescript
async function listApiKeys() {
  const res = await fetch(`${BASE}/apiKeys/list`, { headers: JWT_HEADERS })
  return res.json()
}

const result = await listApiKeys()
// result.data.total
// result.data.api_keys[].id, .name, .api_key, .scopes, .created_at
```

---

## Delete API Key

DELETE https://api.aiozpin.network/api/apiKeys/{id}

```typescript
async function deleteApiKey(id: string) {
  const res = await fetch(`${BASE}/apiKeys/${id}`, {
    method: 'DELETE',
    headers: JWT_HEADERS
  })
  return res.json()
}

await deleteApiKey('api-key-id')
// result.message: "API key has been deleted"
```

---

## Test Authentication

GET https://api.aiozpin.network/api/apiKeys/testAuthentication

Verifies that a pinning API key and secret key are valid.

```typescript
async function testAuthentication(apiKey: string, secretKey: string) {
  const res = await fetch(`${BASE}/apiKeys/testAuthentication`, {
    headers: {
      'pinning_api_key': apiKey,
      'pinning_secret_key': secretKey
    }
  })
  return res.json()
}

const result = await testAuthentication(
  process.env.AIOZ_PIN_API_KEY!,
  process.env.AIOZ_PIN_SECRET_KEY!
)
// result.message: "Congratulations! You are communicating with the Web3 IPFS API!"
```