# Authentication

All embed APIs require authentication using API keys. This guide covers authentication methods for each API endpoint.

## Overview

embed provides three main API services, each with slightly different authentication requirements:

1. **Feed Management API** - Create and manage feed configurations for Farcaster and Zora content
2. **Feed Deployment API** - Get personalized feed recommendations for Farcaster and Zora content
3. **Polymarket Alpha API** - Get personalized Polymarket market recommendations

## Getting Your API Key

All API keys can be obtained from the [embed Console](https://console.mbd.xyz). Once you have your API key, use it according to the authentication method required by each API.

***

## Feed Management API

**Base URL:** `https://console-api-us-west-2.mbd.xyz`

The Feed Management API uses **Basic authentication** format.

### Authentication Method

Include your API key in the `Authorization` header using the `Basic` authentication scheme:

```
Authorization: Basic mbd-{your-api-key}
```

### Example

```bash
curl -X POST "https://console-api-us-west-2.mbd.xyz/api/feed/config" \
  -H "Authorization: Basic mbd-a4790a01cf57c80b08afc644e717c28c4e49f629bc399b55d75fb63a6bee885f" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Feed",
    "endpoint": "casts/feed/for-you",
    "status": "active",
    "visibility": "private",
    "config": {
      "candidate_source": "farcaster-items",
      "candidate_source_type": "posts"
    }
  }'
```

### Code Examples

**JavaScript/Node.js:**

```javascript
const response = await fetch(
  "https://console-api-us-west-2.mbd.xyz/api/feed/config",
  {
    method: "POST",
    headers: {
      Authorization:
        "Basic mbd-a4790a01cf57c80b08afc644e717c28c4e49f629bc399b55d75fb63a6bee885f",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "My Feed",
      endpoint: "casts/feed/for-you",
      status: "active",
      visibility: "private",
      config: {
        candidate_source: "farcaster-items",
        candidate_source_type: "posts",
      },
    }),
  }
);
```

**Python:**

```python
import requests

headers = {
    'Authorization': 'Basic mbd-a4790a01cf57c80b08afc644e717c28c4e49f629bc399b55d75fb63a6bee885f',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://console-api-us-west-2.mbd.xyz/api/feed/config',
    headers=headers,
    json={
        'name': 'My Feed',
        'endpoint': 'casts/feed/for-you',
        'status': 'active',
        'visibility': 'private',
        'config': {
            'candidate_source': 'farcaster-items',
            'candidate_source_type': 'posts'
        }
    }
)
```

***

## Feed Deployment API

**Base URL:** `https://api.mbd.xyz/v2/farcaster`

The Feed Deployment API uses **Bearer token** authentication format.

### Authentication Method

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

```
Authorization: Bearer mbd-{your-api-key}
```

**Important:** The `Bearer` prefix is required. Most API clients will automatically add this prefix when using the HTTP bearer scheme.

### Example

```bash
curl -X POST "https://api.mbd.xyz/v2/farcaster/casts/feed/for-you" \
  -H "Authorization: Bearer mbd-a4790a01cf57c80b08afc644e717c28c4e49f629bc399b55d75fb63a6bee885f" \
  -H "Content-Type: application/json" \
  -d '{
    "feed_id": "feed_390",
    "user_id": "1",
    "top_k": 25,
    "return_metadata": true
  }'
```

### Code Examples

**JavaScript/Node.js:**

```javascript
const response = await fetch(
  "https://api.mbd.xyz/v2/farcaster/casts/feed/for-you",
  {
    method: "POST",
    headers: {
      Authorization:
        "Bearer mbd-a4790a01cf57c80b08afc644e717c28c4e49f629bc399b55d75fb63a6bee885f",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      feed_id: "feed_390",
      user_id: "1",
      top_k: 25,
      return_metadata: true,
    }),
  }
);
```

**Python:**

```python
import requests

headers = {
    'Authorization': 'Bearer mbd-a4790a01cf57c80b08afc644e717c28c4e49f629bc399b55d75fb63a6bee885f',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.mbd.xyz/v2/farcaster/casts/feed/for-you',
    headers=headers,
    json={
        'feed_id': 'feed_390',
        'user_id': '1',
        'top_k': 25,
        'return_metadata': True
    }
)
```

***

## Polymarket Alpha API

**Base URL:** `https://polymarket-api.getembed.ai`

The Polymarket Alpha API uses **Bearer token** authentication format. It supports both direct API keys and JWT tokens.

### Authentication Method

Include your API key or JWT token in the `Authorization` header using the `Bearer` authentication scheme:

```
Authorization: Bearer {your-token}
```

**Token Types:**

* **Direct API keys:** Prefixed with `mbd_` (e.g., `mbd-a4790a01cf57c80b08afc644e717c28c4e49f629bc399b55d75fb63a6bee885f`)
* **JWT tokens:** Standard JWT format

### Example

```bash
curl -X POST "https://polymarket-api.getembed.ai/for-you" \
  -H "Authorization: Bearer mbd-a4790a01cf57c80b08afc644e717c28c4e49f629bc399b55d75fb63a6bee885f" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "0x1234567890123456789012345678901234567890",
    "top_k": 25,
    "return_metadata": true
  }'
```

### Code Examples

**JavaScript/Node.js:**

```javascript
const response = await fetch("https://polymarket-api.getembed.ai/for-you", {
  method: "POST",
  headers: {
    Authorization:
      "Bearer mbd-a4790a01cf57c80b08afc644e717c28c4e49f629bc399b55d75fb63a6bee885f",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    user_id: "0x1234567890123456789012345678901234567890",
    top_k: 25,
    return_metadata: true,
  }),
});
```

**Python:**

```python
import requests

headers = {
    'Authorization': 'Bearer mbd-a4790a01cf57c80b08afc644e717c28c4e49f629bc399b55d75fb63a6bee885f',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://polymarket-api.getembed.ai/for-you',
    headers=headers,
    json={
        'user_id': '0x1234567890123456789012345678901234567890',
        'top_k': 25,
        'return_metadata': True
    }
)
```

***

## Error Responses

All APIs return standard HTTP status codes for authentication errors:

### 401 Unauthorized

Returned when:

* The API key is missing
* The API key is invalid or expired
* The authentication format is incorrect

**Example Response:**

```json
{
  "error": "AuthenticationError",
  "message": "Invalid or expired API key. Please check your credentials at console.mbd.xyz",
  "details": null
}
```

### Common Issues

1. **Missing Authorization Header**

   * Ensure the `Authorization` header is included in all requests
   * Check that the header name is spelled correctly (case-sensitive)

2. **Incorrect Authentication Format**

   * Feed Management API: Use `Basic mbd-{key}` format
   * Feed Deployment API: Use `Bearer mbd-{key}` format
   * Polymarket Alpha API: Use `Bearer {token}` format

3. **Invalid API Key**

   * Verify your API key at [console.mbd.xyz](https://console.mbd.xyz)
   * Ensure the API key hasn't been revoked or expired
   * Check that you're using the correct API key for the service

4. **Wrong Base URL**
   * Feed Management API: `https://console-api-us-west-2.mbd.xyz`
   * Feed Deployment API: `https://api.mbd.xyz/v2/farcaster`
   * Polymarket Alpha API: `https://polymarket-api.getembed.ai`

***

## Security Best Practices

1. **Never commit API keys to version control**

   * Store API keys in environment variables
   * Use secrets management tools in production

2. **Use environment variables:**

   ```bash
   export EMBED_API_KEY="mbd-a4790a01cf57c80b08afc644e717c28c4e49f629bc399b55d75fb63a6bee885f"
   ```

3. **Rotate API keys regularly**

   * Generate new keys periodically
   * Revoke old keys that are no longer in use

4. **Use HTTPS only**

   * All embed APIs require HTTPS
   * Never send API keys over unencrypted connections

5. **Restrict API key permissions**
   * Only grant necessary permissions to each API key
   * Use different keys for different environments (development, staging, production)

***

## Quick Reference

| API              | Base URL                                | Authentication Format | Header                            |
| ---------------- | --------------------------------------- | --------------------- | --------------------------------- |
| Feed Management  | `https://console-api-us-west-2.mbd.xyz` | Basic                 | `Authorization: Basic mbd-{key}`  |
| Feed Deployment  | `https://api.mbd.xyz/v2/farcaster`      | Bearer                | `Authorization: Bearer mbd-{key}` |
| Polymarket Alpha | `https://polymarket-api.getembed.ai`    | Bearer                | `Authorization: Bearer {token}`   |

***

## Support

For authentication issues or questions:

* Check your API key at [console.mbd.xyz](https://console.mbd.xyz)
* Contact support: [support@mbd.xyz](mailto:support@mbd.xyz)
* Review API documentation for endpoint-specific requirements