authentication

Header  mosaic-api-key: YOUR_API_KEY

Publisher Authentication

As a publisher integrating Mosaic into your AI, you'll need to authenticate your requests using an API key. This key is unique to each AI model in your ecosystem and enables us to:

• Track impressions and clicks for your revenue calculations

• Deliver the most relevant ads for your specific model's audience

• Provide accurate analytics and reporting

API Key SecurityYour API key is tied directly to your earnings. Protect it as you would protect your payment credentials.

How to Authenticate

Authentication with Mosaic is straightforward - simply include your API key in the HTTP headers of all requests:

GET /api/fetch-ads HTTP/1.1
Host: demo.xmosaic.ai
Content-Type: application/json
mosaic-api-key: YOUR_API_KEY

Example with cURL

curl -X POST \
  https://demo.xmosaic.ai/api/fetch-ads \
  -H 'Content-Type: application/json' \
  -H 'mosaic-api-key: YOUR_API_KEY' \
  -d '{
    "conversation": "I am looking for hiking shoes for my trip to Colorado",
    "context_keywords": "hiking,shoes,outdoor,travel,Colorado"
  }'

Example with JavaScript

async function fetchAd(conversation, keywords) {
  const response = await fetch('https://demo.xmosaic.ai/api/fetch-ads', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'mosaic-api-key': process.env.MOSAIC_API_KEY // Store in environment variables
    },
    body: JSON.stringify({
      conversation,
      context_keywords: keywords
    })
  });

  return response.json();

Obtaining an API Key

API keys are provided to publishers when they register their AI models with Mosaic. The registration process is simple:

1. Sign up for a Mosaic publisher account at xmosaic.ai

2. Register your AI model with basic information (name, description, link)

3. Receive your unique API key for that model

4. Integrate the key into your application

If you run into any issues or need help with an API key, contact the Mosaic team to get started.

Multiple Models

If you operate multiple AI models, you should use a separate API key for each one. This allows for:

• Independent tracking of performance metrics

• Model-specific ad targeting

• Granular reporting on revenue by model

API Key Security Best Practices

Your API key grants access to request ads on behalf of your AI model and is directly tied to your revenue. Follow these security best practices:

Keep it Secret
Never expose your API key in client-side code or public repositories

Backend Usage
Make API calls from your backend services, not directly from user clients

Environment Variables
Store your API key in environment variables, not hardcoded in your application

Regular Rotation
Periodically rotate your API keys as part of your security practices

Authentication Errors

If authentication fails, the API will return a 404 error with the following response:

{
  "error": "Invalid API Key or model not active"
}

Troubleshooting Authentication Issues

API Key Management

Once your publisher account is set up, you'll have access to a dashboard where you can:

• View all your API keys

• Generate new keys

• Monitor usage statistics

If you suspect your API key has been compromised, immediately contact the Mosaic team