Sessions

A back office session is a short-lived token that acts as one specific member of your TrustWix team. Everything your staff do from your own interface is done with one.

Before you start

Your owner sets your user id for them on each member's page under Team. Whatever you call that person internally goes in that field. A member with the field empty can use our console and cannot be reached from your back office at all, which is also how you switch one person off without touching anything else they hold.

Only an owner can set it, and it asks for their authenticator code.

Getting a session

curl -X POST https://api.trustwix.com/v1/console/sessions \
  -H "Authorization: Bearer $TRUSTWIX_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "u_88213"}'

{
  "object": "console_session",
  "token": "…",
  "expires_at": "2026-08-31T12:10:00.000Z",
  "access": "read_write",
  "member": { "id": "…", "external_id": "u_88213", "role": "reviewer" },
  "environments": ["sandbox", "live"],
  "capabilities": ["reviews.read", "reviews.decide", "verifications.read", "…"]
}

Server side only

This call presents your secret key. Make it from your backend, never from a browser and never from a mobile app. Tokens are short-lived precisely so that repeating this from a server is cheap.

Your key needs the console:session permission, which is granted on request rather than by default, because it is the one scope that mints credentials acting as your people. It cannot be added by an API call, only by an owner or by us.

Use the token, not the key

Every /v1/console/* request carries the token in place of your key:

curl https://api.trustwix.com/v1/console/reviews \
  -H "Authorization: Bearer $SESSION_TOKEN"

Your secret key does not work on these endpoints, and the token does not work on the rest of the API. They are separate credentials for separate jobs.

What `capabilities` is for

Render your interface from it: show the Approve button when the list contains reviews.decide, hide it when it does not. It saves your staff filling in a decision they are not allowed to make.

It is a hint, not the control. We re-check on every request, so a stale list costs you a refused call and never a wrong outcome.

Expiry and revocation

Ask for what you need with ttl_seconds (60 to 3600, default 600). Exchange again when it expires; there is no refresh.

Four things end a session immediately, before its expiry:

What your owner does	Effect
Clears their user id on the Team page	That person's back office access stops
Suspends the seat	Both console and back office stop
Removes a permission	That capability stops being honoured
Revokes the API key	No new sessions can be minted

The first three take effect on the next request, not when the token expires, because we read the seat from the database every time rather than trusting the token to remember.

Read-only sessions

A session minted with a read-only key can read everything the seat can and write nothing. access comes back as read_only, the capability list is narrowed to match, and every write answers 403 READ_ONLY_KEY.

This is how you put the queue in front of people who should see it and not act on it.