Skip to main content
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:
HeaderValuePurpose
X-API-KEYYour secret API keyAuthenticates the request
X-CLIENT-IDYour Client IDIdentifies 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. For browser flows, use the Web SDK with a short-lived SDK token instead — 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"
  }'

​
Credential types

Authmatech issues different credentials for different surfaces. Use the right one for the right place.
CredentialHeaderWhere it’s usedScope
API keyX-API-KEYYour backend → all server APIs (/v1/api/**)Full account access. Keep secret.
Client IDX-CLIENT-IDEvery requestIdentifies your account. Not a secret, but required.
SDK tokenX-SDK-TOKENBrowser/mobile SDK → /v1/api/sdk/session onlyNarrow scope. Cannot call Verify or any server API. Safe for the client.
Client secret—Unlocks sensitive operations such as API-key rotationLong-lived. Keep secret.
The SDK token exists precisely so you never put your API key in client code. The Web SDK registers a session with the SDK token; your backend then performs the verification 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. See Generate an API key and Rotate an API key.

​
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 for client code.
  • 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.
StatusMeaningHow to fix
401 UnauthorizedX-API-KEY or X-CLIENT-ID missing, malformed, or invalidConfirm both headers are present and copied exactly from the dashboard
400 Bad RequestThe product or feature isn’t enabled for your accountCheck your plan, or contact support@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.

​
Next steps

Quickstart

See authentication in a complete working call.

API authentication reference

The headers, scopes, and error shapes in detail.