Authentication

The Partners API uses Bearer token authentication. All API requests must include a valid API token in the Authorization header.

Token Format

Partner API tokens follow a specific format:

• Prefix: mp_live_
• Example: mp_live_YOUR_TOKEN_HERE

Authentication Header

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

Authorization: Bearer mp_live_YOUR_TOKEN_HERE

Making Authenticated Requests

Example Request

curl -X GET "https://api-alpha.markopolo.ai/v1/partners/merchant" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN_HERE"

Authentication Errors

All authentication failures return a consistent response to prevent information leakage:

Status Code: 401 Unauthorized Error Code: AUTHENTICATION_ERRORMessage: "Authentication required"

Common Authentication Issues

Authentication errors can occur for various reasons:

• Missing Authorization Header - The request doesn't include the Authorization header
• Invalid Token Format - Token doesn't start with mp_live_ or has invalid format
• Invalid or Revoked Token - The token has been revoked or never existed
• Malformed Bearer Format - Header isn't in the format Bearer mp_live_YOUR_TOKEN

Standardized Error Response

{
  "message": "Authentication required",
  "code": "AUTHENTICATION_ERROR",
  "statusCode": 401
}

The API intentionally returns the same error response for all authentication failures to prevent attackers from determining which tokens exist or are valid.

For comprehensive error handling including authentication errors, see the Error Handling Guide.

Token Security Best Practices

Keep Your Token Secure

• Never expose your token in client-side code - API tokens should only be used in server-side applications
• Store tokens securely - Use environment variables or secure key management systems
• Don't commit tokens to version control - Add token files to .gitignore

Environment Variables

Store your token in environment variables for security. Use your platform's standard environment variable practices to keep tokens out of your codebase.

Testing Authentication

Test your authentication setup with a simple request:

curl -X GET "https://api-alpha.markopolo.ai/v1/partners/merchant?limit=1" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN_HERE"

A successful response indicates your token is valid and properly configured.

Partner Isolation

The API automatically isolates data based on the authenticated partner:

• Each token is associated with a specific partner account
• You can only access merchants created under your partner account
• Attempting to access another partner's resources returns 404 Not Found
• All merchant operations verify partner ownership

Getting Your API Token

To obtain your API token and get started as a partner:

1. Contact partners@markopolo.ai to begin the onboarding process
2. Business Review - Our team will learn about your platform and integration needs
3. Receive API Token - You'll get your unique token (prefixed with mp_live_)
4. Secure Storage - Store your API token securely - it won't be shown again

For detailed onboarding information and marktag type options, see the Overview.

Troubleshooting

Common Issues

All authentication failures return the same error for security:

{
  "message": "Authentication required",
  "code": "AUTHENTICATION_ERROR",
  "statusCode": 401
}

If you receive this error, check the following:

1. Authorization Header

   • Ensure the header is included in your request
   • Verify the format: Authorization: Bearer mp_live_YOUR_TOKEN

2. Token Format

   • Confirm your token starts with mp_live_
   • Check for extra spaces or characters in the token

3. Token Validity

   • Ensure you're using the correct token provided during onboarding
   • Contact support if you believe your token should be valid

4. Network Issues

   • Verify network connectivity to the API
   • Implement retry logic with exponential backoff for transient failures