Authentication

Send API credentials on every request, rotate keys safely, and troubleshoot common authentication errors.

MasterID authenticates every API request with a workspace-scoped API Key and API Secret. You must include both headers on every call. The Merchant ID identifies your workspace but does not authenticate requests. This page shows how to send credentials securely, store them safely, rotate them without downtime, and resolve 401 and 403 errors.

Required headers

Send these headers on every request:

Header	Value
X-API-Key	Your API key
X-API-Secret	Your API secret
Content-Type	application/json

Examples

cURL

curl -s https://masterid.me/api/public/v1/catalog \
  -H "X-API-Key: $MASTERID_API_KEY" \
  -H "X-API-Secret: $MASTERID_API_SECRET" \
  -H "Content-Type: application/json"

Secret storage best practices

Never include API credentials in browser JavaScript, public repositories, URLs, analytics, or application logs.

• Store your API Key and API Secret in a dedicated secret manager (for example, AWS Secrets Manager, HashiCorp Vault, or Azure Key Vault).
• Read credentials into environment variables at runtime. Example .env file for local development:
  .env

  MASTERID_API_KEY=your-api-key
  MASTERID_API_SECRET=your-api-secret
  
• Rotate credentials if they are ever logged, committed, or exposed.
• Secrets cannot be recovered after their first display is closed. Save both values securely when they are first generated.

Merchant ID is not a credential

Your Merchant ID appears alongside your API credentials but does not authenticate requests. It is used for merchant-specific operations such as payment collection. Using a different workspace’s Merchant ID in a collection request returns HTTP 403.

Credential rotation and deletion

Regenerating credentials replaces the API Key, API Secret, and Merchant ID together. Existing credentials stop working immediately. Update every integration that uses the old values before regenerating.

1. Prepare new credentials

   Open the Developer Console and generate a new credential pair. Record both values securely.

2. Update all integrations

   Deploy the new API Key and API Secret to every service, worker, and scheduled job that calls the MasterID API.

3. Verify every integration

   Send a low-risk request (for example, GET /wallet or GET /catalog) from each service to confirm the new credentials are active.

4. Remove old values

   Delete the old API Key and API Secret from secret stores, environment variables, and configuration files. If you use a secret manager, mark the old version as deprecated or delete it.

5. Delete or rotate the webhook secret if needed

   The webhook signing secret is separate from API authentication. It cannot be used as an API Secret. To replace it, delete the current webhook and add another in the Developer Console.

Deleting credentials stops all API access for that workspace. Ensure at least one active credential pair exists before deleting.

Webhook signing secret

Webhooks are signed with a separate secret you configure in the Developer Console. To verify webhook signatures, compute an HMAC SHA-256 over timestamp + '.' + rawBody using the signing secret. See the Webhooks guide for the full verification flow. The webhook signing secret cannot be used as an API Secret.

Troubleshooting

HTTP 401: missing, invalid, or revoked credentials

• Check that both X-API-Key and X-API-Secret headers are present.
• Verify the values match an active credential pair in the Developer Console.
• Confirm the credentials have not been regenerated or deleted since they were last used.

HTTP 403: suspended account or Merchant ID mismatch

• Ensure your workspace account is in good standing.
• For collection requests, ensure the merchantId matches the Merchant ID of the authenticated workspace. A different Merchant ID is rejected.
• Confirm merchant activation is complete if you are collecting payments.

Support

If you need help, contact MasterID support at [e-mail] or call [phone].