X-API-Key header on every request. The key determines which customer scope and data tiers you can access.
Obtaining a key
Trassets sets up the portal access for your organization; there is no public sign-up. With that access, an administrator at your organization logs in at portal.api.trassets.ai and generates API keys from the dashboard themselves. The plaintext key is displayed exactly once. Copy it immediately and store it in a secure secrets manager. If you lose it, you must revoke the old key and create a new one.Passing the key in requests
Include theX-API-Key header on every call. Here is a minimal curl example against a live /v1/ table:
Key types
Every key has a type,raw or transformed. The type decides whether the key may read raw source tables. An administrator sets it in the portal; keys created for customers are transformed.
A
raw key cannot carry restrictions. Reading a raw table additionally needs both personal data grants, personal and personal_financial, because raw tables cannot be split by column; /v1/raw/tables lists the tables either way. A transformed key gets no raw data and no tables without a category.
If /v1/raw/tables is empty although the key is valid, the key is transformed. If a raw table returns 403 with detail “Raw export requires an API key of type raw with personal data grants. Contact your administrator or Trassets support.”, the key is transformed or lacks one of the two grants — ask your administrator or Trassets support. A changed key type or grant takes effect within about a minute.
Personal data grants
Columns with personal data — names, contact and bank details of tenants, owners, employees, and creditors, names of staff and assignees, and free-text fields such as comments, which can contain any of these — belong to one of two classes,personal and personal_financial. A key sees a class only with the matching grant; personal does not include personal_financial. Without the grant, /v1/{category}/{table} returns the rows without those columns. ID columns and property_id always remain. Exception: the booking texts booking_headers.booking_text and booking_positions.booking_position_text are not classified and are visible to every key, although they occasionally contain names.
Grants apply to every key, raw or transformed, and override a column filter that names the column. Raw tables need both grants (see above). An administrator sets grants in the portal; a change takes effect within about a minute.
Property restrictions
Atransformed key can additionally be limited to a list of property IDs. Category endpoints then return only rows of those properties, and a table that has no property_id column (for example /v1/stakeholder/creditors) returns 403 for such a key. /v1/catalog and /v1/changes are not filtered by property; they list tables, not rows. An administrator sets the property list in the portal; a key without a list sees all properties.
Account restrictions
A key can additionally be limited to positions of theTrassets-Standard reporting structure (see account_hierarchies in Accounting). /v1/accounting/accounts, booking_positions, budgets, and account_hierarchies then return only rows whose account (property_id + account_id) is assigned to one of those positions. /v1/accounting/booking_headers and /v1/raw/{table_name} return 403 for such a key, and /v1/raw/tables returns an empty list. Other categories are not filtered by account; a key created without a category selection is limited to Accounting. An administrator selects the positions in the portal when creating the key; they can’t be changed afterwards, create a new key instead. A key without positions sees all accounts.
Key storage and security
Trassets never stores your API key in plaintext. Only an HMAC-SHA-256 hash is retained on our servers for verification. This means we cannot recover or display a key after creation. Treat your key like a password:- Do not commit it to version control.
- Rotate keys regularly: generate a new key in the portal, switch your integration over, then delete the old one. The Last Used column in the portal shows when a key last made a successful request (updated at most once per hour). Use it to check that the old key is no longer in use before you delete it. There is no one-click rotation.
- Scope each key to the minimum access tier your integration needs.
Authentication errors
If the key is missing, invalid, or does not have the required access tier, the API returns an RFC 7807 problem response.401 Unauthorized
X-API-Key header.
403 Forbidden
Invalid API key) or disabled (API key is disabled), or it is valid but the requested endpoint or data tier is not included in your subscription. Read the detail field to tell the cases apart. Contact your account administrator or Trassets support to change your access.