Authentication and routing

Wafeq issues your organization's API key. Its prefix identifies its mode. Send
the complete key in the Authorization header on every API request:

Authorization: Api-Key pk_test_<your-test-key-secret>

For an enabled live integration, the header is:

Authorization: Api-Key pk_live_<your-live-key-secret>

The current public pilot uses NBR sandbox and test keys. Live issuance requires
Wafeq to enable and confirm NBR core access. A key for the wrong mode returns
HTTP 401; editing a key's prefix does not change its mode or make it valid.

Existing pilot keys beginning nbr_sk_ remain valid for test use only. Ask Wafeq
to rotate one to a pk_test_ key. Rotation replaces the old key; no automatic
rotation changes existing integrations.

Keep the key on your server. Do not embed it in a browser application, mobile app
or public repository.

Check your organization

The examples in these guides use these shell variables. Replace the key before
running them:

BASE=https://api.wafeq.com/bh/v1
KEY=pk_test_replace_with_your_complete_issued_key

curl "$BASE/organizations/me" \
  -H "Authorization: Api-Key $KEY"

The response identifies your organization and its configured legal details.
api_key_mode reports test or live for the stored key; a legacy pilot key
reports test. Missing, malformed, invalid or wrong-mode credentials return
HTTP 401.

The separate staging deployment also uses test keys, but has its own credentials
and data. A pk_test_ prefix does not make a staging key valid on the public
pilot deployment.

Choose the taxpayer and branch

For device registration, document validation and submission, send the connected
account's ID. A DIRECT account with more than one active branch also needs the
branch header:

X-NBR-Connected-Account-Id: <connected-account-id>
X-NBR-Sub-CR: <branch-sub-cr>

For DIRECT accounts, X-NBR-Sub-CR selects the taxpayer's signing device. For
THIRD_PARTY accounts, Wafeq selects the provider organization's active device;
the branch header records the supplier branch and does not select another
provider certificate.

Your key can access only your organization's connected accounts, devices and
documents. Organization profile and provider device endpoints do not need a
connected-account header. List and summary document endpoints can use the
headers to narrow results to one taxpayer or branch.