Authentication and keys

The header

Every request carries your key as a bearer token. There is no other mechanism: no cookies, no session, no OAuth flow and no query parameter. A key in a URL ends up in logs, browser history and referrer headers.

Authorization: Bearer nsk_live_...

Keys

• A key belongs to one account, and everything it can see is scoped to that account. There is no cross-account access.
• Keys are created and managed in Settings, Developer, on a paid Enterprise plan, by the license administrator or a user they have given Developer access.
• A key is shown once, at creation. NutraSoft stores a SHA-256 hash of it, so a lost key cannot be recovered: revoke it and create another.
• Settings shows each key's prefix and last four characters, so you can tell keys apart without seeing them.
• An account holds up to 50 active live keys and 50 active test keys. A rotated key keeps its place; revoke keys you no longer use.
• Revocation is immediate. A revoked key fails on its next request.

Rotating a key without an outage

Rotate a key from Settings, Developer and choose a grace period: none, 1 hour, 24 hours, 7 days. You get a new key, shown once, and the old key keeps working until the grace period ends. While it does, its responses carry a Sunset header with the time it stops, so you can deploy the new key without taking your integration down.

1. Rotate the key with a grace period long enough to cover a deploy.
2. Deploy the new key everywhere the old one is used.
3. Watch for responses that still carry Sunset: they come from something still using the old key.

A key that is already revoked, or already inside a grace period, cannot be rotated again.

Environments

One base URL for both. The pairing is checked both ways: a test key against a live account is refused, and a live key against a test account is refused. Both come back as 401 INVALID_API_KEY with the same message as every other key failure, so an unauthenticated caller never learns why a key was rejected.

Scopes

A key carries scopes, so you can issue a narrow key for a narrow job. Every operation in the reference shows the scope it needs. GET /organization needs none and reports the key's effective scopes.

• A write scope implies the matching read scope within its own module, and nothing else. sales:write grants sales:read; it does not grant catalog:read.
• cost:read is standalone. Nothing grants it implicitly, and the "Read everything" preset in Settings leaves it out. Without it every cost and price field reads null, which means redacted, not zero. You can give a fulfilment integration full sales access without giving it your margins.
• A call without the scope it needs returns 403 INSUFFICIENT_SCOPE.

When the plan changes

The API needs a paid Enterprise plan, and test keys follow the plan of the account that owns them. If the plan lapses or moves below Enterprise, live and test keys both get 403 NOT_ENTITLED. On a plan without the API, the license administrator, and anyone with Developer access, can still list and revoke keys and delete the test account, so nothing is left behind. While no plan is active at all, NutraSoft opens only its billing page, so that cleanup waits until a plan is active again.

Failed authentication

Repeated failed authentication from one IP address is throttled. Past the limit, every further invalid key from that address gets 429 RATE_LIMITED instead of 401 until the minute rolls over, so fix the key rather than retrying. A valid key from the same address keeps working.

Keeping keys safe

• Server side only. A key in a browser or a mobile app is a published key.
• One key per integration, so you can revoke one without breaking the others.
• Give each key the narrowest set of scopes that does its job.
• Grant Developer access sparingly. Whoever holds it can create a key with every scope, costs included, whatever their other permissions in NutraSoft.
• Rotate on a schedule, and when someone with access to a key leaves, using a grace period.