API
Authentication
How to authenticate requests to a TWIN supply-chain node.
Every API call requires two things: a session cookie (obtained by logging in) and an x-api-key (provided by your node operator). Policy endpoints additionally accept a Bearer JWT extracted from the cookie.
| Credential | Where it comes from | Used on |
|---|---|---|
x-api-key | Your node operator | Every request, including login |
Session cookie (access_token) | POST /authentication/login | DSC and data endpoints |
| Bearer JWT | Extracted from the session cookie | Policy endpoints |
POST /authentication/login
Log in to obtain a session cookie.
POST /authentication/login
Content-Type: application/json
x-api-key: <your-api-key>{
"email": "user@example.com",
"password": "your-password"
}Response 200
The JWT is delivered via Set-Cookie, not the response body.
Set-Cookie: access_token=<jwt>; HttpOnly; Path=/; SameSite=Strict{
"expiry": 1719150000000,
"identity": "did:entity-storage:0x..."
}expiry is milliseconds since Unix epoch. identity is the DID of the authenticated user.
Errors
| Status | Cause |
|---|---|
401 | Wrong email or password |
400 | Missing or malformed field |
POST /authentication/login/create
Provisions a new user account on the node. Use this only if your node operator asks you to self-provision — accounts are normally created during onboarding.
POST /authentication/login/create
Content-Type: application/json
x-api-key: <your-api-key>{
"email": "user@example.com",
"password": "your-password",
"profileName": "Alice",
"organizationId": "did:entity-storage:0x..."
}| Field | Required | Description |
|---|---|---|
email | Yes | Email address for the new account |
password | Yes | Password |
profileName | No | Display name |
organizationId | No | DID of an existing organisation to join. If omitted, a new organisation is created. |
Response 201
{
"token": "<jwt>",
"expiry": 1704067200000,
"identity": "did:entity-storage:0x...",
"organizationId": "did:entity-storage:0x...",
"apiKey": "<your-x-api-key>"
}apiKey is your x-api-key for subsequent API calls.
Error codes
| Status | Cause |
|---|---|
400 | Missing or invalid field |
401 | Missing x-api-key header |
404 | organizationId not found in this node |
500 | Email already registered |