Authentication

All requests to the Mapademics Embedded API must be authenticated.

Authentication is handled using API keys that identify:

• Your platform (you, the integrator)

• Your end customer (in production environments)

This page explains which keys you need, how to obtain them, and how to use them correctly in test and production.

---

Authentication at a glance

• All API requests require an API key

• Test and production environments use different keys

• Production requests typically require both:

  • Your platform API key

  • An end-customer API key

You include API keys as HTTP headers on every request.

---

API key types

Platform API key

Your platform API key identifies your application and grants access to the Embedded API.

You will have separate keys for:

• Test

• Production

These keys are created and managed in the Embedded API Portal.

Treat platform API keys as secrets. Never expose them in client-side code.

---

End-customer API key (production only)

In production, requests are scoped to a specific end customer.

An end-customer API key:

• Identifies the customer on whose behalf the request is made

• Allows Mapademics to correctly scope data, usage, and billing

• Is required for most production API calls

End-customer keys are typically created programmatically or via your internal workflows, depending on your integration.

---

Test vs production environments

Test environment

In the test environment:

• Only a platform test API key is required

• End-customer keys are not required

• Data and usage are non-production

This environment is intended for development and integration testing.

Note: The test environment contains only a subset of the full data set. However, all requests and responses conform to the API spec, so your integration code will work the same way in production.

---

Production environment

In the production environment:

• A platform production API key is always required

• Most requests also require an end-customer API key

• Requests are fully scoped, metered, and subject to production limits

---

Making authenticated requests

API keys are sent using HTTP headers.

Example: authenticated request (cURL)

curl https://embedded-api.mapademics.com/v1/example-endpoint \
  -H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \
  -H "X-Customer-Key: YOUR_END_CUSTOMER_API_KEY"

In test environments, the X-Customer-Key header is typically not required.

JavaScript example

fetch("https://embedded-api.mapademics.com/v1/example-endpoint", {
  headers: {
    Authorization: `Bearer ${process.env.MAPADEMICS_API_KEY}`,
    "X-Customer-Key": process.env.MAPADEMICS_CUSTOMER_KEY,
  },
});

Python example

import requests

headers = {
  "Authorization": "Bearer YOUR_PLATFORM_API_KEY",
  "X-Customer-Key": "YOUR_END_CUSTOMER_API_KEY",
}

response = requests.get(
  "https://embedded-api.mapademics.com/v1/example-endpoint",
  headers=headers,
)

---

Key management best practices

• Store API keys in environment variables or secure secrets managers

• Never commit API keys to source control

• Do not expose platform API keys in client-side applications

• Rotate keys if you believe they may have been compromised

---

Common authentication errors

401 Unauthorized

Cause

Missing or invalid platform API key

How to fix

• Verify the Authorization header is present

• Ensure you are using the correct key for the environment

---

403 Forbidden

Cause

Missing or invalid end-customer API key (production)

How to fix

• Confirm the X-Customer-Key header is included

• Verify the customer key is valid and active

---

What to do next

• Quick Start – Make your first API call in minutes

• Syllabus Skills Extraction – End-to-end examples for skills extraction

• Labor Market Intelligence – End-to-end examples for labor market data

If you have questions about authentication or key management, contact the Mapademics team.