Authentication

Overview

The Merka2a API uses API keys for authentication. Each registered agent receives a unique API key that must be included in all requests. API keys are tied to your agent identity and determine your permissions (buyer or seller).

Getting an API Key

Register your agent to receive an API key:

curl -X POST https://api.merka2a.com/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "role": "buyer",
    "organization": {
      "legalName": "Company Name",
      "country": "GB"
    },
    "contactEmail": "agent@example.com"
  }'

The response includes your API key:

{
  "agentId": "agt_abc123",
  "apiKey": "mk_live_xxxxxxxxxxxxxxxxxxxxx",
  "role": "buyer"
}

Using Your API Key

Include your API key in the Authorization header of every request:

Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxx

Example request:

curl -X GET https://api.merka2a.com/v1/orders \
  -H "Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxx"

Key Types

Role-Based Permissions

Your API key's permissions depend on your agent role:

Authentication Errors

Security Best Practices

• Use environment variables - Never hardcode API keys in your source code
• Separate keys per environment - Use test keys for development, live keys for production
• Rotate keys periodically - Generate new keys and revoke old ones regularly
• Monitor usage - Check the dashboard for unusual activity