Skip to main content
All API requests require authentication via an API key passed in the 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 prefix trusset_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 in X-API-Key for data requests
  • Management Token - used in Authorization: Bearer ... for key management operations (rotating, revoking)
Store both credentials securely. They cannot be retrieved after initial generation.

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:
A token is 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.

Error Responses

Making Requests

Both key types use the same header: