Authentication and roles

Every request to the public twin endpoints must be authenticated. How you authenticate also decides which fields come back: the endpoints always return a twin's public fields, and can additionally return fields that are restricted to a particular role.

Field visibility

Each custom attribute in NexTwin carries a visibility setting, which determines whether its values appear in a public API response:

Visibility	Meaning	Returned by the public API
public	Anyone may see the field.	Always.
private_by_role	Only the roles selected on the attribute may see the field.	Only when the request asks for a role that the attribute grants.
private	Internal to the owning organization.	Never.

Top-level twin fields (id, token id, status, product type, trade nr, batch nr, quantity, unit, organization, facility, documents, IPFS hash) are always returned. Visibility applies to the custom fields under dynamicFields.

note

private fields are never exposed through the public API, no matter which role is requested. Only private_by_role fields can be unlocked by a role.

Authenticating with an API key

Pass your key in the X-Api-Key header. See Creating an API key for how to obtain one.

curl 'https://app.nextwin.io/ps/twins/public/123' \
  -H 'X-Api-Key: abc123'

This returns the twin's public fields. An invalid, inactive, or expired key is rejected with 401 Unauthorized.

Requesting role-restricted fields

To also receive the fields a given role may see, add the role query parameter. The response then contains both the public fields and that role's private_by_role fields — it is additive, not a replacement.

curl 'https://app.nextwin.io/ps/twins/public/123?role=logistics' \
  -H 'X-Api-Key: abc123'

This is the intended integration pattern for platforms that front NexTwin data with their own login. For example, when a user signs in to GoodsLedger with the Logistics role and opens a passport, the GoodsLedger backend calls NexTwin with its API key and role=logistics; NexTwin validates the key and returns the public data together with the Logistics data.

The flow in that example:

1. The user logs in to GoodsLedger with the Logistics role and opens a passport.
2. The GoodsLedger backend requests the passport from NexTwin, sending its own X-Api-Key and role=logistics.
3. NexTwin validates the API key and resolves the role.
4. NexTwin returns the public data plus the Logistics data.
5. GoodsLedger renders the passport.

Note that the end user's own login happens entirely in GoodsLedger. NexTwin does not see the user's session — it sees the integrating platform's API key and the role that platform asserts, so the platform is responsible for sending the role that matches the signed-in user.

Accepted values

The role parameter accepts either form:

• A role name, such as logistics. Matching is case-insensitive.
• A role id, such as 66f1a2b3c4d5e6f708192a3b.

Role names are not guaranteed to be unique across organizations. When a name matches several roles, the request is evaluated against all of them, and a field is returned if any of those roles is permitted to see it.

Rules and edge cases

• A valid API key is required for role to take effect. On a request without one, the parameter is ignored and only public fields are returned. This prevents a caller who is merely reaching the API from an allowlisted browser origin from reading restricted data by guessing a role name.
• An unknown role name is not an error. The request succeeds and returns the public fields only, so a typo shows up as missing fields rather than a failed call.
• Requesting one role returns only that role's fields. Ask for the role whose view you need; you cannot request several roles in a single call.
• A 502 Bad Gateway means the role could not be resolved, not that it does not exist. This is a transient failure — retry the request.

The role parameter is supported on the two twin lookup endpoints:

• GET /{twinid}
• GET /{tradeNr}/{batchNr}

Authenticating with a JWT session

Requests made from a signed-in NexTwin browser session (the __session cookie holding the JWT issued at login) are recognised automatically. Such a caller receives the twin's complete set of custom fields, matching what the authenticated application shows — so the role parameter is neither needed nor applied.

This path exists to serve the NexTwin frontend itself. Server-to-server integrations should use an API key with the role parameter, which does not depend on a browser session and is scoped to exactly one role's view.

Caller	Field set returned
Valid API key	Public fields
Valid API key + role	Public fields + that role's fields
Signed-in NexTwin session (JWT)	All custom fields