Skip to main content
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.

​
Login Token Authentication

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

​
OrgCode
string
required
Your organization code. This identifies which Nymble Commerce tenant you are authenticating against. Example: org_52a3021e813.
​
ClientId
string
required
Your client ID. Issued when your API credentials are provisioned. Acts as the username component of your credential pair.
​
ClientSecret
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

​
AccessToken
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.
​
TokenType
string
The token scheme. Always returns "api-key".
​
ExpiresIn
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:
ClaimTypeDescription
OrganizationIdstringThe unique ID of your Nymble Commerce organization. Used to scope all data access — products, customers, orders, and more.
CustomerNumberstringThe customer account number associated with the authenticated user. Scopes cart and order operations to that customer.
PriceTierstringThe pricing tier assigned to the customer (e.g., Wholesale, Retail). Applied automatically when listing products and calculating order totals.
CurrencyCodestringThe 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.
RoleAccess level
AdminFull access to all organization resources: customers, products, orders, invoices, payments, settings, and analytics. Required for bulk operations, customer management, and organization configuration.
CustomerAccess to their own account, the product catalog, their carts, and their order and invoice history. Cannot access other customers’ data.
SalesRepAccess 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 StatusErrorCause and resolution
401 UnauthorizedMissing or invalid credentialYour 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 ForbiddenInsufficient role or permissionsYour 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 RequestsRate limit exceededYou’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.