Authentication

Nucleo does not have one API key for everything. Each API uses the credential that fits where the code runs and whose data it touches:

Publishable keys identify your store, not a person. They are meant to live in your theme's code, so they never give read access to your data: what protects them is the list of domains they may be used from.

Both can be rotated from the same page: the old value stops working at once, so update your theme in the same deploy.

Shoppers never get an account or a password from these APIs. They prove who they are with what they already have:

• Returns — the shopper looks the order up with its number plus the email address or the shipping postcode. Nucleo answers with a session token (header X-Return-Session) valid for 60 minutes and for that order only. Each return created gets its own long random return token that opens its status page and its label.
• Tracking — every parcel has a signed tracking token, the last segment of the tracking link in shipping notifications (…/track/{token}). It shows the parcel's progress and nothing else.

Server tokens read or change data. Keep them on your servers, in a secret store, and never ship them to a browser or a mobile app.

• CMS delivery token (cmsdt_…) — reads the published content of one site. Create it in Nucleo under CMS > your site > Settings > For developers > Create token. The value is shown once. Send it as Authorization: Bearer cmsdt_….
• Warehouse credentials — issued for one warehouse connection when the integration is set up. The T-Data interface accepts them as X-Api-Key, as a Bearer token or as HTTP Basic; the FFW interface as described in its reference. See Connect a warehouse.

curl https://api-brain.nucleoplatform.com/api/delivery/v1/acme/sites/12/menus \
  -H "Authorization: Bearer $NUCLEO_CMS_TOKEN"

const res = await fetch("https://api-brain.nucleoplatform.com/api/delivery/v1/acme/sites/12/menus", {
  headers: { Authorization: `Bearer ${process.env.NUCLEO_CMS_TOKEN}` },
});

<?php

$client = new GuzzleHttp\Client();
$res = $client->get('https://api-brain.nucleoplatform.com/api/delivery/v1/acme/sites/12/menus', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('NUCLEO_CMS_TOKEN')],
]);

When software acts on behalf of a person — an AI assistant reading the catalog, an internal tool drafting a reply — it uses OAuth 2.0. The person signs in to Nucleo, sees a consent screen and approves; your client receives an access token that carries that person's permissions, in the company they choose, and nothing more.

• Authorization server: https://auth.nucleoplatform.com (discovery at /.well-known/oauth-authorization-server and /.well-known/openid-configuration).
• Flow: authorization code with PKCE (S256).
• Clients register themselves with Dynamic Client Registration (RFC 7591) at /oauth/register: no need to ask us for a client id.
• Tokens of self-registered clients carry the scope nucleo.ai_tools: they work on the MCP connector and the AI tools, on userinfo and to revoke themselves, and nowhere else.

The AI assistants guide walks through the whole flow.

When a carrier or a tracking service pushes parcel events to Nucleo, each request is signed with the secret of the carrier connection it is addressed to: X-Nucleo-Signature is the lowercase hex HMAC-SHA256 of the exact raw body. See Webhooks.

When Nucleo calls your endpoint (the CMS revalidate call), it signs the request with the secret you configured: Nucleo-Signature: t=<unix time>,v1=<hex HMAC-SHA256 of "t.body">. See Webhooks.

• Store server tokens and secrets in environment variables or a secret manager, never in a repository.
• Give each integration its own credential, so you can rotate one without touching the others.
• Rotate immediately if a server token may have leaked: rotation in Nucleo takes effect at once.
• Restrict publishable keys to the domains you really use.
• Treat any 401 you did not expect as a signal: the credential may have been rotated by someone in your team.