Nymble Commerce API Authentication: Tokens, API Keys & Roles

Nymble Commerce supports two authentication methods. Use credential-based login tokens for user-facing applications where your server exchanges credentials for a scoped token. Use x-api-key header authentication for machine-to-machine (M2M) integrations where a pre-issued API key is passed directly in every request. Choose the method that matches your integration architecture — both grant access to the same API surface, scoped to your organization.

Use login token authentication when your application authenticates on behalf of a user or customer session. Your server exchanges your OrgCode, ClientId, and ClientSecret for a short-lived access token, then passes that token in the x-api-key header on all subsequent requests.

Endpoint

POST /api/auth/login

Request body

string

required

Your organization code. This identifies which Nymble Commerce tenant you are authenticating against. Example: org_52a3021e813.

string

required

Your client ID. Issued when your API credentials are provisioned. Acts as the username component of your credential pair.

string

required

Your client secret. Issued alongside your ClientId. Treat this as a password — never expose it in client-side code or public repositories.

Response fields

string

A signed access token. Pass this value in the x-api-key header of every subsequent API request. The token encodes your organization context and role claims so you don’t need to pass them separately.

string

The token scheme. Always returns "api-key".

integer

The token’s lifetime in seconds. Typically 86400 (24 hours). Cache the token and reuse it until it approaches expiry rather than requesting a new one on every call.

Example request

curl -X POST https://api.achievemomentum.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "OrgCode": "org_52a3021e813",
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret"
  }'

Example response

{
  "AccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJPcmdhbml6YXRpb25JZCI6IjY1OTA0OTM3NDU3MzE0MjIyYzNmMWNiNCIsIkN1c3RvbWVyTnVtYmVyIjoiQ1VTVDQ1NiIsIlByaWNlVGllciI6Ildob2xlc2FsZSIsIkN1cnJlbmN5Q29kZSI6IlVTRCIsInJvbGUiOiJDdXN0b21lciIsImV4cCI6MTczNTY4OTYwMH0.fake_signature",
  "TokenType": "api-key",
  "ExpiresIn": 86400
}

Using the token

Pass the AccessToken value in the x-api-key header on every subsequent request:

curl -X GET https://api.achievemomentum.com/api/products \
  -H "x-api-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Accept: application/json"

The /api/auth/login endpoint is rate-limited to 10 requests per minute per ClientId. If you exceed this limit, you’ll receive a 429 Too Many Requests response. Cache your token and reuse it for its full ExpiresIn duration to stay well within this limit.

API Key Authentication

For server-to-server integrations, automated pipelines, and backend services, use a pre-issued API key instead of the credential login flow. Pass your API key directly in the x-api-key request header.

curl -X GET https://api.achievemomentum.com/api/products \
  -H "x-api-key: your-api-key" \
  -H "Accept: application/json"

API keys are scoped to your organization and bypass the credential login flow entirely — there’s no expiry to manage and no login call required. This makes them ideal for:

ERP and accounting system integrations
Scheduled data sync jobs
Webhook processors and event-driven pipelines
Internal tooling that runs with elevated or admin-level access

Contact your Nymble Commerce account administrator to obtain or rotate your organization’s API key. API keys carry the same organizational scope as a login token but are not tied to an individual user session.

Token claims

When you authenticate via POST /api/auth/login, the returned AccessToken encodes your organization context. The Nymble Commerce API reads these claims on every request, so you don’t need to pass organization context explicitly in most endpoints. Key claims carried in the token:

Claim	Type	Description
`OrganizationId`	string	The unique ID of your Nymble Commerce organization. Used to scope all data access — products, customers, orders, and more.
`CustomerNumber`	string	The customer account number associated with the authenticated user. Scopes cart and order operations to that customer.
`PriceTier`	string	The pricing tier assigned to the customer (e.g., `Wholesale`, `Retail`). Applied automatically when listing products and calculating order totals.
`CurrencyCode`	string	The currency for this session (e.g., `USD`, `CAD`). Used to format prices consistently across catalog and order responses.

These claims are populated when your API credentials are provisioned and enriched at login time.

Authorization roles

Every Nymble Commerce user or integration is assigned a role that determines which API endpoints and resources are accessible. Roles are configured during account provisioning.

Role	Access level
Admin	Full access to all organization resources: customers, products, orders, invoices, payments, settings, and analytics. Required for bulk operations, customer management, and organization configuration.
Customer	Access to their own account, the product catalog, their carts, and their order and invoice history. Cannot access other customers’ data.
SalesRep	Access to the accounts and orders assigned to that rep. Can place and manage orders on behalf of assigned customers. Cannot access accounts outside their assignment.

Roles are set when your account is provisioned. To add, change, or remove roles for a user or integration credential, contact Nymble Commerce support.

Common authentication errors

HTTP Status	Error	Cause and resolution
`401 Unauthorized`	Missing or invalid credential	Your request is missing the `x-api-key` header, the token is malformed, or the token has expired. Re-authenticate to get a new token and retry.
`403 Forbidden`	Insufficient role or permissions	Your token is valid but your role doesn’t have access to the requested resource. Check that your role (Admin, Customer, SalesRep) is appropriate for the endpoint you’re calling.
`429 Too Many Requests`	Rate limit exceeded	You’ve exceeded 10 login requests per minute on `/api/auth/login`. Implement token caching to avoid repeated logins. Back off and retry after 60 seconds.

Security best practices

Never expose your ClientSecret in client-side code. Your ClientSecret is equivalent to a password. Keep it server-side only — in environment variables or a secrets manager — and never commit it to source control or embed it in mobile apps or browser JavaScript.

Use API keys for server-to-server integrations. For backend services, cron jobs, and ERP integrations, use a pre-issued API key via the x-api-key header rather than the credential login flow. API keys have no expiry to manage and avoid the overhead of token exchange.

Cache login tokens until near expiry. A token is valid for ExpiresIn seconds (typically 86,400 seconds / 24 hours). Store it in memory or a short-lived cache and reuse it across requests. Refresh it only when it’s within a few minutes of expiry. This keeps you well within the login rate limit and reduces latency.

Rotate credentials immediately if compromised. If you suspect your ClientSecret or API key has been exposed, contact Nymble Commerce support to rotate your credentials. Previously issued tokens will be invalidated when credentials are rotated.

Get Started

Core Concepts

Guides

Help

Nymble Commerce API Authentication: Tokens, API Keys & Roles

Endpoint

Request body

Response fields

Example request

Example response

Using the token

API Key Authentication

Token claims

Authorization roles

Common authentication errors

Security best practices

​Login Token Authentication

​Endpoint

​Request body

​Response fields

​Example request

​Example response

​Using the token

​API Key Authentication

​Token claims

​Authorization roles

​Common authentication errors

​Security best practices

Login Token Authentication

Endpoint

Request body

Response fields

Example request

Example response

Using the token

API Key Authentication

Token claims

Authorization roles

Common authentication errors

Security best practices