Authentication

All API requests require authentication using API keys passed in request headers.

Embedded API Portal

All Embedded API customers get access to the Embedded API Portal where you can:

• View your primary API keys (pk_live and pk_test)

• Provision and manage end-customer API keys

• Monitor usage and billing

Contact [email protected] to get portal access.

API Key Types

Primary API Keys

Your primary authentication credentials. You'll have two keys:

Key Type	Format	Environment
Test Key	pk_test_xxxxxxxxxxxxxxxx	embedded-api.testing.mapademics.com
Live Key	pk_live_xxxxxxxxxxxxxxxx	embedded-api.mapademics.com

End-Customer API Keys

End-customer keys identify which of your customers is making the API call. You provision these in the Embedded API Portal.

Key Type	Format
End-Customer Key	ck_xxxxxxxxxxxxxxxx

End-customer keys enable:

• Per-customer usage tracking and billing

• Per-customer rate limits

• Customer-specific analytics

Authentication Requirements

Important: Testing and production have different authentication requirements.

Testing Environment

Calls to embedded-api.testing.mapademics.com require only your test key:

Header	Required	Value
X-API-Key	Yes	pk_test_xxx
X-End-Customer-API-Key	No	Not required

cURL

curl -X GET "https://embedded-api.testing.mapademics.com/v1/skills" \
  -H "X-API-Key: pk_test_xxxxxxxxxxxxxxxx"

TypeScript

Python

Production Environment

Calls to embedded-api.mapademics.com require both your live key and an end-customer key:

Header	Required	Value
X-API-Key	Yes	pk_live_xxx
X-End-Customer-API-Key	Yes	ck_xxx

cURL

curl -X GET "https://embedded-api.mapademics.com/v1/skills" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxx" \
  -H "X-End-Customer-API-Key: ck_customer123"

TypeScript

Python

Testing vs Production Summary

Aspect	Testing	Production
Base URL	embedded-api.testing.mapademics.com	embedded-api.mapademics.com
Primary Key	pk_test_xxx	pk_live_xxx
End-Customer Key	Not required	Required
Data	Sample/synthetic	Real
Rate Limits	Higher (for development)	Standard
Billing	Not billed	Billed per request

Start with testing. The testing environment doesn't require end-customer keys, making it easier to get started during development.

Managing End-Customer Keys

Creating End-Customer Keys

1. Log into the Embedded API Portal

2. Navigate to End-Customer Keys

3. Click Create New Key

4. Enter a name/identifier for the customer

5. Copy the generated ck_xxx key

Best Practices

• Create one key per end-customer for accurate usage tracking

• Store keys securely - treat them like passwords

• Rotate keys periodically if you suspect compromise

• Revoke unused keys to maintain security

Security Best Practices

Never Expose Keys in Client-Side Code

API keys should never appear in:

• JavaScript running in browsers

• Mobile app source code

• Public repositories

• Client-side configuration files

Wrong: Hardcoding keys in frontend code

// NEVER DO THIS
const API_KEY = "pk_live_abc123xyz"; // Exposed to anyone viewing source

Correct: Proxy requests through your backend

// Your backend server
app.get("/api/labor-market/:cipCode", async (req, res) => {
  const response = await fetch(
    `https://embedded-api.mapademics.com/v1/labor-market-intelligence/cip/${req.params.cipCode}`,
    {
      headers: {
        "X-API-Key": process.env.MAPADEMICS_LIVE_KEY,
        "X-End-Customer-API-Key": req.user.mapademicsCustomerId,
      },
    }
  );
  res.json(await response.json());
});

Use Environment Variables

Store API keys in environment variables, not in code:

# .env (add to .gitignore!)
MAPADEMICS_TEST_KEY=pk_test_xxxxxxxxxxxxxxxx
MAPADEMICS_LIVE_KEY=pk_live_xxxxxxxxxxxxxxxx

Rotate Keys Periodically

We recommend rotating your API keys every 90 days:

1. Generate a new key in the Embedded API Portal

2. Update your application to use the new key

3. Verify the new key works correctly

4. Revoke the old key

API Versioning

The API uses path-based versioning. The current version is v1 and is included in all endpoint URLs:

https://embedded-api.mapademics.com/v1/skills
https://embedded-api.mapademics.com/v1/labor-market-intelligence/cip/11.0701

We maintain backward compatibility within major versions. Breaking changes are announced at least 6 months in advance and released as a new major version (e.g., /v2).

Authentication Errors

Error Code	HTTP Status	Meaning
UNAUTHORIZED	401	Missing or invalid API key
FORBIDDEN	403	Valid key but missing end-customer key or insufficient permissions

Example Error Response

{
  "object": "error",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid X-API-Key header",
    "documentationUrl": "https://docs.mapademics.com/authentication"
  }
}

See the FAQ & Common Issues for troubleshooting authentication problems.