> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masterid.co.ug/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash cURL theme={null}
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"
```

```javascript client.js theme={null}
// Reusable fetch wrapper for Node.js 18+
const BASE = "https://masterid.me/api/public/v1";

async function masteridFetch(path, opts = {}) {
  const res = await fetch(`${BASE}${path}`, {
    ...opts,
    headers: {
      "X-API-Key": process.env.MASTERID_API_KEY,
      "X-API-Secret": process.env.MASTERID_API_SECRET,
      "Content-Type": "application/json",
      ...opts.headers,
    },
  });

  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new Error(body.error || `HTTP ${res.status}`);
  }
  return res.json();
}

(async () => {
  const { data } = await masteridFetch("/wallet");
  console.log("Balance:", data.balance, data.currency);
})();
```

```python client.py theme={null}
# Reusable client for Python (requests)
import os, requests

BASE = "https://masterid.me/api/public/v1"
AUTH_HEADERS = {
    "X-API-Key": os.environ["MASTERID_API_KEY"],
    "X-API-Secret": os.environ["MASTERID_API_SECRET"],
    "Content-Type": "application/json",
}


def masterid_request(method, path, **kwargs):
    url = f"{BASE}{path}"
    headers = {**AUTH_HEADERS, **kwargs.pop("headers", {})}
    r = requests.request(method, url, headers=headers, **kwargs)
    r.raise_for_status()
    return r.json()


data = masterid_request("GET", "/wallet")["data"]
print("Balance:", data["balance"], data["currency"])
```

## Secret storage best practices

> [!WARNING]
>
> 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:
  ```bash .env theme={null}
  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.

> [!WARNING]
>
> 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](https://docs.masterid.co.ug/guides/webhooks.md) 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 [sales@masterid.co.ug](mailto:sales@masterid.co.ug) or call +256 771 922 513.


## Related topics

- [API Overview](https://docs.masterid.co.ug/api-reference/overview.md)
- [Quickstart](https://docs.masterid.co.ug/quickstart.md)
- [MasterID Integration API](https://docs.masterid.co.ug/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.