Guides
Start typing to search…

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

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:

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:

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

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:

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:

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

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:

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:

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:

{
  "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
    • 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:

    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

APIBase URLAuthentication FormatHeader
Feed Managementhttps://console-api-us-west-2.mbd.xyzBasicAuthorization: Basic mbd-{key}
Feed Deploymenthttps://api.mbd.xyz/v2/farcasterBearerAuthorization: Bearer mbd-{key}
Polymarket Alphahttps://polymarket-api.getembed.aiBearerAuthorization: Bearer {token}

Support

For authentication issues or questions:

Updated 2 days ago