> ## Documentation Index
> Fetch the complete documentation index at: https://core.anylayer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate with the ZKScore API

## API Key Authentication

ZKScore API uses Bearer token authentication. All API requests must include your API key in the Authorization header.

### Getting an API Key

1. Visit the [Developer Portal](https://builder.onzks.com)
2. Connect your wallet
3. Navigate to "API Keys"
4. Click "Create New API Key"
5. Copy and securely store your key

<Warning>
  Your API key is shown only once. Store it securely and never expose it in client-side code.
</Warning>

## Making Authenticated Requests

Include your API key in the `Authorization` header with the `Bearer` scheme:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api-mainnet.onzks.com/api/v1/scores/0x... \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript/TypeScript theme={null}
  const response = await fetch('https://api-mainnet.onzks.com/api/v1/scores/0x...', {
    headers: {
      'Authorization': `Bearer ${YOUR_API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': f'Bearer {YOUR_API_KEY}',
      'Content-Type': 'application/json'
  }

  response = requests.get(
      'https://api-mainnet.onzks.com/api/v1/scores/0x...',
      headers=headers
  )
  ```
</CodeGroup>

## API Key Permissions

API keys can have different permission levels:

| Permission | Description                     |
| ---------- | ------------------------------- |
| `read`     | Read-only access to public data |
| `write`    | Create and update resources     |
| `admin`    | Full access including deletions |

<Tip>
  Use the minimum required permissions for your use case to enhance security.
</Tip>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Never Expose Keys Client-Side">
    Always make API calls from your backend server. Never include API keys in:

    * Frontend JavaScript code
    * Mobile app code
    * Public repositories
    * Client-side environment variables
  </Accordion>

  <Accordion title="Use Environment Variables">
    Store API keys in environment variables, not in your code:

    ```bash .env theme={null}
    ZKSCORE_API_KEY=your_api_key_here
    ```

    ```javascript theme={null}
    const apiKey = process.env.ZKSCORE_API_KEY;
    ```
  </Accordion>

  <Accordion title="Rotate Keys Regularly">
    Rotate your API keys periodically and immediately if compromised:

    1. Create a new API key
    2. Update your application
    3. Revoke the old key
  </Accordion>

  <Accordion title="Use Different Keys for Different Environments">
    Create separate API keys for development, staging, and production:

    * `dev-app-name`
    * `staging-app-name`
    * `prod-app-name`
  </Accordion>
</AccordionGroup>

## Error Responses

### 401 Unauthorized

Missing or invalid API key:

```json theme={null}
{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "timestamp": "2025-10-22T10:30:00Z"
}
```

### 403 Forbidden

Insufficient permissions:

```json theme={null}
{
  "success": false,
  "error": "FORBIDDEN",
  "message": "Insufficient permissions for this operation",
  "timestamp": "2025-10-22T10:30:00Z"
}
```

## Managing API Keys

### Create a New Key

```bash theme={null}
POST /api/v1/developer/keys
```

```json theme={null}
{
  "name": "My Application",
  "permissions": ["read"],
  "rateLimit": 100
}
```

### List Your Keys

```bash theme={null}
GET /api/v1/developer/keys
```

### Revoke a Key

```bash theme={null}
DELETE /api/v1/developer/keys/:keyId
```

<Card title="Developer API Reference" icon="code" href="/api-reference/developer/create-api-key">
  View complete API key management documentation
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Make Your First Request" icon="rocket" href="/quickstart">
    Follow the quick start guide
  </Card>

  <Card title="Explore API Endpoints" icon="list" href="/api-reference/introduction">
    Browse all available endpoints
  </Card>
</CardGroup>