Authentication

The Truss API uses API keys to authenticate requests. Each key belongs to one user in your firm, and requests made with it act as that user: they see the projects, contacts, and files that user can see in Truss, and anything they create is attributed to that user.

Where to get your API key

Sign in to Truss. Open the menu in the top-right corner and choose Integrations.
Under API Key, click Generate API Key.
Copy the key and store it in your secrets manager. Truss shows the key once. After you leave the page, only the date it was generated is visible.

Generating a new key invalidates the previous one immediately. Any integration still using the old key, including Zapier, stops working until you update it.

Only full-access users can generate and use API keys. A key held by a limited-access user is rejected, including keys created before that user's access was restricted.

Using your API key

Send the key in the Authorization header with the Bearer scheme on every request.

curl https://app2.gettruss.io/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

The key is a single opaque string. Send it exactly as Truss displayed it. It already identifies both the user and the secret, so there is no separate username or account id to pass.

Truss also accepts the key in an X-API-KEY header, or with the Token scheme in place of Bearer. These exist for older integrations; use Bearer in new code.

Keeping your key safe

Your API key carries every permission its user has in Truss. Treat it like a password.

Don't embed the key in source code, mobile apps, or anything that runs in a browser. Keep it on your server and load it from a secrets vault or an environment variable.
Generate the key from a dedicated integration user where you can, so that rotating it or deactivating the user doesn't affect a person's login.
Rotate the key by generating a new one. The old key stops working the moment the new one is issued, so update your configuration before you switch traffic.

Authentication errors

Make all API requests over HTTPS. Calls made over plain HTTP are redirected and will not carry your credentials. Requests without a valid key fail with a 4xx status and a JSON body:

Status	`errors`	Meaning
`403`	`No authorization provided`	The request had no `Authorization` or `X-API-KEY` header.
`403`	`Authentication failed`	The key is malformed, doesn't match any user, or was invalidated by generating a new one.
`403`	`API key access is restricted to full-access users.`	The key belongs to a limited-access user.
`403`	`API key access is unavailable for this firm.`	The firm's plan doesn't include API access.
`401`	`Invalid token format`	The bearer value contains characters that can't be an API key.

{ "errors": "Authentication failed" }

If you see Authentication failed after a key worked before, the most common cause is that someone generated a new key from the Integrations page.