X-API-Key header. Trusset uses two key systems depending on the API you are accessing. The one exception is the KYC Inbox, which a bank’s KYC verifier calls with a bearer token.
Instance API Keys
Instance API keys authenticate requests to the core platform APIs (Customers, Token imports, Trading, Lending, Custody). Each key is bound to a specific and grants access only to that instance’s data and services. The current key format is:instanceRef is an 8-character alphanumeric identifier for your instance. secret is a 64-character hex string. A complete key is 81 characters long.
Instance API keys are managed through the Issuer Platform or via the key management API. Keys support rotation with a configurable overlap period: when you rotate a key, the old key enters a PENDING_ROTATION state and remains valid for 7 days, giving you time to update all consumers without downtime. Each instance supports up to 10 active keys.
Archiving an instance stops its keys at once: the next request with any of them answers 401 AUTH_FAILED.
The key decides which instance a request acts on. A request that also carries an instanceId in the query string or body must send it as a single string. An object or a list answers 400 INVALID_INSTANCE_ID before anything else runs.
Endpoints protected by instance auth also enforce service-level access. If your instance does not have a required service enabled (e.g.,
tokenization), the request returns 403 with code SERVICE_NOT_ENABLED.Error Responses
MiCA Register API Keys
The MiCA Register API uses its own key system with the prefixtrusset_mica_. These keys are free and provide access exclusively to the MiCA Register endpoints.
Register at trusset.org/mica-register to generate your key. After registration you receive two credentials:
- API Key (
trusset_mica_...) - used inX-API-Keyfor data requests - Management Token - used in
Authorization: Bearer ...for key management operations (rotating, revoking)
Error Responses
KYC Inbox Tokens
The KYC Inbox is called by a KYC verifier that a bank designated as one of its KYC sources. It takes no API key. The verifier sends the token from the bank’s invite as a bearer token:tki_ followed by 43 base64url characters and opens one source’s inbox at one bank instance. It is shown only inside the invite. The bank ends it by issuing a new invite or by removing the source. Every delivery and every revocation is also signed with the verifier’s own Ed25519 key, which the token does not replace.
