Authentication

Every request to the TrustWix API is authenticated with a secret API key sent as a bearer token.

curl https://api.trustwix.com/v1/verifications \
  -H "Authorization: Bearer TWK_..." \
  -H "Content-Type: application/json"

Two kinds of credential

A secret key identifies your account and carries the permissions attached to it. It reads TWK_ followed by one long opaque token and has no other structure. It is issued in the console, shown once at creation, and stored only as a hash on our side. If you lose it, revoke it and create a new one. Secret keys belong on your server and nowhere else.

A client token is minted for you when you create a verification and is returned as client_token on the create response. It is scoped to that single verification, expires within minutes, and is the only credential that may be handed to a browser or a mobile client. Treat it as an opaque string, never parse it, and never cache it beyond the session it belongs to.

Environments

The environment is a property of the key itself, not a different host and not a header. One base URL serves both.

You pick the environment when you create the key, and it is fixed for the life of that key. Because the token carries no environment marker, there is nothing in the string to parse: read the environment from the console, where every key is listed against the environment it belongs to, or from mode on any verification the key creates.

Sandbox and live data never mix. A test key cannot read a live verification and a live key cannot read a sandbox one, so an accidental cross-environment call fails cleanly rather than returning the wrong record.

Permissions

Keys carry scopes, so a key that only needs to create verifications does not also need to manage webhooks or read applicants. Calling an endpoint your key is not scoped for returns 403 permission_error. Create narrow keys per integration rather than one key for everything, and revoke the narrow ones freely.

Rotation

Create the replacement key first, deploy it, confirm traffic has moved, then revoke the old key. Revocation takes effect immediately, so the reverse order causes an outage. Key ids, their environment and a truncated form of each key are visible in the console for exactly this reason.

Request correlation

Every response carries an X-Request-Id header. You can also send your own X-Request-Id and it will be echoed back. Log it. It is the fastest way for support to find a specific request, and it is included in every error body as error.request_id.