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

# Authmatech API Authentication: API Keys & Client ID

> Authenticate Authmatech API requests with the X-API-KEY and X-CLIENT-ID headers. Learn credential types, where each is used, and security best practices.

Every request to the Authmatech API must be authenticated. Authmatech uses **API-key authentication** with two headers that travel together on every server-side call:

| Header        | Value               | Purpose                                         |
| ------------- | ------------------- | ----------------------------------------------- |
| `X-API-KEY`   | Your secret API key | Authenticates the request                       |
| `X-CLIENT-ID` | Your Client ID      | Identifies which account the request belongs to |

<Warning>
  The API key is a **server-side secret**. Never ship it to the browser, a mobile binary, or any client-side code. The native [mobile SDKs](/sdks/mobile) use a narrow-scoped SDK token instead, and the browser [Web SDK](/sdks/web) is transaction-based — see [Credential types](#credential-types) below.
</Warning>

## Finding your credentials

Your credentials live in the [Authmatech dashboard](https://dashboard.authmatech.com):

* **Client ID** — always visible in your account.
* **API key** — generated on demand. The raw key is displayed **once** at generation; afterward only its fingerprint is stored. If you lose it, rotate to issue a new one.

## Including credentials in requests

Send both headers on every request:

```
X-API-KEY: YOUR_API_KEY
X-CLIENT-ID: YOUR_CLIENT_ID
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://service.authmatech.com/v1/api/verify \
    -H "X-API-KEY: YOUR_API_KEY" \
    -H "X-CLIENT-ID: YOUR_CLIENT_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "mobileNumber": "+962791234567",
      "encryptedMobileNumber": "BASE64_ENCRYPTED_BLOB_FROM_SDK",
      "operatorId": "ZAIN_JO",
      "serviceType": "LOGIN"
    }'
  ```

  ```python Python theme={null}
  import os
  import requests

  headers = {
      "X-API-KEY": os.environ["AUTHMATECH_API_KEY"],
      "X-CLIENT-ID": os.environ["AUTHMATECH_CLIENT_ID"],
      "Content-Type": "application/json",
  }

  payload = {
      "mobileNumber": "+962791234567",
      "encryptedMobileNumber": "BASE64_ENCRYPTED_BLOB_FROM_SDK",
      "operatorId": "ZAIN_JO",
      "serviceType": "LOGIN",
  }

  resp = requests.post(
      "https://service.authmatech.com/v1/api/verify",
      headers=headers,
      json=payload,
  )
  print(resp.status_code, resp.json())
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch("https://service.authmatech.com/v1/api/verify", {
    method: "POST",
    headers: {
      "X-API-KEY": process.env.AUTHMATECH_API_KEY,
      "X-CLIENT-ID": process.env.AUTHMATECH_CLIENT_ID,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      mobileNumber: "+962791234567",
      encryptedMobileNumber: "BASE64_ENCRYPTED_BLOB_FROM_SDK",
      operatorId: "ZAIN_JO",
      serviceType: "LOGIN",
    }),
  });

  const data = await resp.json();
  console.log(resp.status, data);
  ```
</CodeGroup>

## Credential types

Authmatech issues different credentials for different surfaces. Use the right one for the right place.

| Credential        | Header        | Where it's used                                       | Scope                                                                 |
| ----------------- | ------------- | ----------------------------------------------------- | --------------------------------------------------------------------- |
| **API key**       | `X-API-KEY`   | Your backend → all server APIs (`/v1/api/**`)         | Full account access. Keep secret.                                     |
| **Client ID**     | `X-CLIENT-ID` | Every request                                         | Identifies your account. Not a secret, but required.                  |
| **SDK token**     | `X-SDK-TOKEN` | Native mobile SDK → `/v1/api/sdk/session` only        | Narrow scope. Cannot call Verify or any server API. Safe for the app. |
| **Client secret** | —             | Unlocks sensitive operations such as API-key rotation | Long-lived. Keep secret.                                              |

<Note>
  The SDK token exists precisely so you never put your API key in app code. The native [mobile SDKs](/sdks/mobile) register a session with the SDK token; your backend then performs the verification with the API key. The browser [Web SDK](/sdks/web) needs no credential client-side — it runs against a transaction id, and your backend resolves the result with the API key.
</Note>

## Rotating your API key

Rotate from the dashboard or via the API whenever a key may be exposed, or on a regular schedule:

* `POST /v1/api/me/api-key/rotate` — rotate your own key (requires your client secret).
* `POST /v1/api/clients/rotate-key` — rotate by client.

After rotating, update every system that uses the old key. The rotation endpoints are listed in the [API reference](/api/overview).

## Security best practices

<Warning>
  Treat the API key like a password. Anyone holding it can verify numbers and consume your balance.
</Warning>

* **Never commit keys to source control.** Use environment variables or a secrets manager. Add `.env` to `.gitignore`.
* **Never expose the API key client-side.** Browser bundles and mobile apps are publicly readable. Use the SDK token in native apps; the Web SDK keeps the key on your server by design.
* **Reference keys from the environment in production** — `process.env.AUTHMATECH_API_KEY` (Node.js), `os.environ["AUTHMATECH_API_KEY"]` (Python).
* **Rotate on exposure** and on a schedule.

```bash theme={null}
# Store credentials as environment variables — never in source
export AUTHMATECH_API_KEY="your_api_key_here"
export AUTHMATECH_CLIENT_ID="your_client_id_here"
```

## Authentication errors

If either header is missing or the key is invalid, the API returns `401 Unauthorized`.

| Status             | Meaning                                                     | How to fix                                                                          |
| ------------------ | ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `401 Unauthorized` | `X-API-KEY` or `X-CLIENT-ID` missing, malformed, or invalid | Confirm both headers are present and copied exactly from the dashboard              |
| `400 Bad Request`  | The product or feature isn't enabled for your account       | Check your plan, or contact [connect@authmatech.com](mailto:connect@authmatech.com) |

<Tip>
  Persistent `401`s with a key you believe is correct are usually caused by trailing whitespace or a line break copied with the key. Make sure the header value contains only the key, with no surrounding quotes.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    See authentication in a complete working call.
  </Card>

  <Card title="API authentication reference" icon="code" href="/api/authentication">
    The headers, scopes, and error shapes in detail.
  </Card>
</CardGroup>