Authentication

Developer reference for authenticating requests to Nector APIs.

API Key Types

Nector issues two categories of API keys:

Type	Access Type	Description
Read-only	`READ`	Used to fetch data. Further scoped by `purpose`: `SERVER` or `STOREFRONT`.
Read-write	`WRITE`	Used to write and mutate data. No lead-level authentication required.

Common Headers

The following headers are mandatory on every API request, regardless of key type or purpose:

Header	Description
`x-apikey`	Your Nector API key.
`x-workspaceid`	Your Nector workspace id.
`x-source`	Origin of the request: `web` (browsers and servers) or `mobile` (native apps).

Read-Only API Keys

Read-only keys (access_type = READ) behave differently depending on their purpose field.

Purpose: SERVER

No additional headers are required. Requests work without lead authentication.

Purpose: STOREFRONT

Storefront read-only keys require lead-level authentication on all customer-scoped endpoints. This ties every request to a specific customer (lead).

There are two lead credential types:

Credential	Header	Description
Lead Digest	`x-leaddigest`	Short-lived HMAC computed server-side to prove identity via `customer_id`. Accepted only on the lead lookup endpoint.
Lead Token	`x-leadtoken`	JWT signed with the API key signing secret. Required on all other customer-scoped endpoints.

Authentication Path A — You Already Have the Nector Lead ID

If you have the Nector’s internal lead id (the _id of the lead), you can generate a lead token directly server-side and skip the digest flow entirely.

JWT payload: { "lead_id": "<nector_lead_id>" }
Algorithm:   HS256
Secret:      <api_signing_secret>
Expiry:      1 hour

Use the token on every subsequent customer-scoped request:

x-leadtoken: <generated-jwt>

Generate lead tokens server-side only. Never expose the signing_secret or generate tokens in the browser.

Authentication Path B — You Only Have the Platform Customer ID

If you only have a platform customer ID (e.g., a Shopify or WooCommerce customer ID), use a digest to call the lead lookup endpoint first and exchange it for a lead token.

Step 1: Compute the Lead Digest

Compute the digest server-side:

payload = "{raw_customer_id}:{current_unix_timestamp}"
digest  = HMAC-SHA256(payload, signing_secret), hex-encoded

raw_customer_id is the customer id without its platform prefix. A prefix of shopify-, woocommerce-, magento- or custom_website- is stripped before computing the digest, so for customer_id shopify-12345678 sign 12345678:{current_unix_timestamp}.

The unix_timestamp (in seconds) must match the value sent in x-timestamp and must be within 60 minutes of the server time.

When sending x-leaddigest, the x-timestamp header is mandatory.

Step 2: Call the Lead Lookup Endpoint

GET /api/v2/merchant/leads/:id

Headers:

x-apikey:      <your-api-key>
x-workspaceid: <your-workspace-id>
x-source:      web | mobile
x-timestamp:   <unix-timestamp>
x-leaddigest:  <hex-encoded-hmac>

Query parameter:

customer_id: shopify-12345678

The :id path parameter can be a random UUID v4. The customer_id is passed as a query param and takes precedence.

Step 3: Extract the Lead Token

If the digest is valid, data in the response includes the lead along with:

{
  "lead_token": "<jwt>"
}

The token is valid for 1 hour.

Step 4: Use the Lead Token

Use the returned token on all subsequent customer-scoped requests:

x-leadtoken: <lead_token>

Endpoint Header Requirements

Endpoint	Accepted Lead Auth
`GET /api/v2/merchant/leads/:id`	`x-leaddigest` or `x-leadtoken`
All other `/api/v2/merchant/*` endpoints	`x-leadtoken` only

The lead lookup endpoint is the only endpoint that accepts a digest. All other customer-scoped endpoints — including wallet transactions, coupons, offer redeems, checkout actions and triggers — require a lead token. When a lead token is passed, the customer is taken from the token and any lead_id or customer_id in the request is ignored.

Security Notes

Always compute digests and lead tokens server-side. Never expose the signing_secret to the browser.
Lead tokens expire after 1 hour. Long-lived sessions need a token refresh strategy.
If origin_ips are configured on the API key, all requests must originate from those allowed IPs.