Authmatech API Authentication: API Keys & Client ID

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

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 use a narrow-scoped SDK token instead, and the browser Web SDK is transaction-based — see Credential types below.

Finding your credentials

Your credentials live in the Authmatech dashboard:

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

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"
  }'

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())

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);

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.

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

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.

Security best practices

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

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.

# 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

Persistent 401s 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.

Get started

Core concepts

Guides

SDKs

Support

Authmatech API Authentication: API Keys & Client ID

Finding your credentials

Including credentials in requests

Credential types

Rotating your API key

Security best practices

Authentication errors

Next steps

Quickstart

API authentication reference

​Finding your credentials

​Including credentials in requests

​Credential types

​Rotating your API key

​Security best practices

​Authentication errors

​Next steps

Quickstart

API authentication reference

Finding your credentials

Including credentials in requests

Credential types

Rotating your API key

Security best practices

Authentication errors

Next steps