Set up the authentication for your API to help users manage their credentials.
| API Key | Label | Last Used | |
|---|---|---|---|
Nector authenticates every request with an API key. Depending on where the call is made from, a customer scoped request may additionally need to prove which customer it acts for. Generate API keys and the signing secret from the dashboard under Settings > API Keys.
Headers on Every Request
| Header | Required | Description |
|---|---|---|
x-apikey | Yes | Your Nector API key. |
x-workspaceid | Yes | Your Nector workspace id. |
x-source | Yes | Origin of the request: web (browsers and servers) or mobile (native apps). |
x-leadtoken | Storefront keys only | The lead token of the customer on customer scoped APIs. |
API Key Types
| Key | Where to use it | What it can do |
|---|---|---|
| Write access | Your backend only | Everything. Required for Create User, Create Wallet Transaction, Create Credit Wallet Transaction, Reward Offer, Reward Cross Selling Offer and Reward Using Trigger for triggers that are not marked open. No customer authentication is needed since your backend is trusted. |
Read only, purpose server | Your backend | All GET APIs and customer facing writes such as Reward Using Trigger for open triggers, Redeem Offer, Checkout Redemption and Create Review. No customer authentication is needed. |
Read only, purpose storefront | Your web or mobile app | Same APIs as the server read only key, but customer scoped APIs need the customer to be authenticated with a lead token in x-leadtoken, so that a visitor cannot act on another customer's account. |
Keep write access keys on your backendNever expose a write access API key in a browser or app. Use read only keys wherever possible.
Storefront Keys and the Lead Token
When a request comes from a browser or app, the customer id cannot be trusted. A storefront read only key therefore requires x-leadtoken on every customer scoped API. The lead token is a JWT that identifies one customer and is valid for 1 hour. When it is passed, the customer is taken from the token and any lead_id or customer_id in the request is ignored.
There are two ways to obtain a lead token. Both need your API signing secret, so both run on your server.
Option A: Generate the Token on Your Server
If your server already knows the Nector lead _id of the customer, sign the token yourself.
JWT payload: { "lead_id": "<nector-lead-id>" }
Algorithm: HS256
Secret: <api-signing-secret>
Expiry: 1 hourSend the token to your storefront and pass it as x-leadtoken on every customer scoped request.
Option B: Exchange a Digest for a Token with Get User
If your storefront only knows your own customer id (for example a Shopify customer id), compute a short lived digest on your server and call Get User with it. This is the only API that accepts a digest.
Step 1: Compute the digest on your server
timestamp = current unix time in seconds
digest = hex( HMAC-SHA256( "<customer-id>:<timestamp>", <api-signing-secret> ) )A platform prefix on the customer id, one of shopify-, woocommerce-, magento- or custom_website-, is stripped before computing the digest. For customer_id shopify-12345 sign 12345:<timestamp>.
Step 2: Call Get User with the digest
The path id can be any placeholder UUID v4, the customer_id query parameter takes precedence.
curl "https://cachefront.nector.io/api/v2/merchant/leads/<any-uuidv4>?customer_id=shopify-12345" \
-H "x-apikey: <storefront-read-only-api-key>" \
-H "x-workspaceid: <your-workspace-id>" \
-H "x-source: web" \
-H "x-timestamp: <timestamp>" \
-H "x-leaddigest: <digest>"
x-timestampis required withx-leaddigestand must be within 60 minutes of the server time.
Step 3: Use the lead token
Read data.lead_token from the response and pass it as x-leadtoken on all other customer scoped requests. The response also carries the wallet, tier and membership of the customer, so no extra call is needed.
Which Lead Credential Each API Accepts
| API | Accepted with a storefront key |
|---|---|
| Get User | x-leaddigest or x-leadtoken |
| All other customer scoped APIs | x-leadtoken only |
Security Notes
- Compute digests and lead tokens on your server only. Never ship the signing secret to a browser or app.
- Lead tokens expire after 1 hour, so refresh them for long sessions.
- Get User masks
emailandmobilein the response. When looked up by email, mobile or referral code with a read only key, it also omits_id,customer_id,wallet_idandcreditwallet_idso that a visitor cannot discover another customer's ids. - If origin IPs are configured on an API key, requests must come from those IPs.