Authentication
Authenticate with secret API keys, scope them to what each integration needs, and keep them safe.
Trimline authenticates requests with secret API keys sent as a bearer token. Each key belongs to one account and one environment, and can be limited to the scopes your integration needs.
Sending your key
Pass the key in the Authorization header on every request.
curl https://api.trimline.tech/v1/vendors \
-H "Authorization: Bearer tl_live_51Jx…"A request without a valid key returns 401 Unauthorized. A valid key that lacks the scope an endpoint needs returns 403 Forbidden with the error code insufficient_scope.
Key types
| Prefix | Environment | Use for |
|---|---|---|
tl_test_ | Sandbox | Development and CI. Works against seeded test data, and drafts are never emailed. |
tl_live_ | Production | Your real vendors and contracts. Approved drafts are sent from your mailbox. |
Scopes
When you create a key, choose the smallest set of scopes it needs. A reporting script only needs read scopes. An approval bot needs drafts:write.
| Scope | Grants |
|---|---|
vendors:read | List and retrieve vendors and contracts |
vendors:write | Update vendor preferences, such as keep and owners |
renewals:read | List and retrieve renewals, negotiations and offers |
renewals:write | Start, pause or close negotiations; accept or decline offers |
drafts:write | Edit, approve, hold and discard drafts. This scope can send email on your behalf. |
savings:read | Read savings and fee records |
connections:write | Create and revoke mailbox and finance connections |
webhooks:write | Manage webhook endpoints |
Keeping keys safe
- Store keys in a secrets manager or environment variables, never in source code.
- Only call the API from your servers. Requests from a browser are blocked by CORS.
- Use a separate key for each integration, so you can revoke one without breaking the others.
- Rotate keys at least once a year, and right away if one might have been exposed. You can roll a key with a 24-hour overlap from Settings → API keys.
If you think a live key has leaked, revoke it immediately and email security@trimline.tech. We’ll help you review recent activity for that key.
Account context
Every response includes a Trimline-Account header with the account ID the key belongs to. That’s useful for confirming which workspace a request touched when you manage more than one.
Something unclear or missing? Email developers@trimline.tech.