Skip to main content
Version: v2

Authentication

This page is the single source of truth for how requests to API v2 are authenticated and attributed. Every other page links here instead of restating the rules.

API Key (required on every endpoint)​

All API v2 endpoints — including market-data endpoints such as GET /currency/, GET /pair/, and GET /rate/ — require an API key.

Send the key in the Authorization header using the ApiKey scheme:

curl -X GET "https://api.n.exchange/en/api/v2/pair/" \
  -H "Accept: application/json" \
  -H "Authorization: ApiKey YOUR_API_KEY"
ApiKey, not Bearer

The scheme name is ApiKey, not Bearer. Authorization: Bearer <key> is rejected.

Requests without a valid key receive 401 Unauthorized:

{
  "detail": "Authentication credentials were not provided."
}

API keys and referral tokens are created self-serve from your personal dashboard on n.exchange. For partner-specific capabilities (trusted pre-screening tokens, dynamic markup), contact support@n.exchange.

Keys are scoped to a trading mode​

A partner account can hold separate referral codes — and matching API keys — per trading mode (CeFi, CeFi fixed-rate, DeFi). Use the key and referral token that belong to the mode you are operating in; a key scoped to one mode does not authorize order flows in another. See Affiliate & Referral for how per-mode referral codes work.

Referral token (x-referral-token)​

The x-referral-token header carries your referral token. It:

  • attributes orders and rate quotes to your referral code (revenue share, partner rate terms),
  • acts as an alternative credential on GET /rate/ (either an API key or a referral token satisfies auth there),
  • is required on POST /pre_screening/ — that endpoint only works with a trusted referral token.
curl -X GET "https://api.n.exchange/en/api/v2/rate/?pairs=BTCETH" \
  -H "Accept: application/json" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "x-referral-token: YOUR_REFERRAL_TOKEN"
Header name

The header is exactly x-referral-token. There is no referral_code header.

Other ways to supply a referral code​

On CeFi order flows the referral code can alternatively be supplied via:

MechanismWhereNotes
x-referral-token headerany requestpreferred for server-to-server integrations
?ref= query parameterorder-creation requests and the widgetalso drives widget attribution
referral_code body fieldPOST /orders/, PATCH /orders/{unique_reference}/max 20 chars, pattern ^[A-Za-z0-9_-]+$
Sessionbrowser flowsset when a user lands via a referral link

Ownership rule​

When a request is authenticated with an API key, any referral code supplied by any mechanism must belong to the same user that owns the API key. A mismatch is rejected.

Optional headers​

HeaderFormatPurpose
X-User-TimezoneGMT ±HH:MM (IANA_Timezone), e.g. GMT +04:00 (Asia/Dubai) (tz list)Optional. Communicates the end user's timezone for time-sensitive flows (payment windows, deadlines shown to the user). Omitting it does not fail requests.

OAuth2 (v1 legacy only)​

OAuth2 exists only in API v1, for user-scoped endpoints such as /user/me/orders and /users/me. API v2 has no OAuth2 endpoints: orders are created for anonymous users and attributed via referral tokens, so the API key + x-referral-token pair covers every v2 flow. If you need v1 user-account features, see the v1 documentation.

Security best practices​

  • Treat API keys and referral tokens as secrets: server-side only, never shipped in client-side JavaScript or mobile binaries.
  • Use the widget for browser embeds — it is designed for client-side use and does not expose your API key.
  • Rotate credentials via support if a leak is suspected.

Next steps​