Get started
Authentication
Every request carries a credential. The REST API takes an API key; the MCP connector takes an API key or an OAuth sign-in.
API keys
Create keys in the dashboard under Developers → API keys. A key belongs to one organization and carries a set of scopes. Test (sandbox) keys start with tflo_test_; live keys will start with tflo_live_. Treat a key like a password and keep it on your server.
A test key sends to the CBP certification environment. A live key sends to production CBP, which is not connected yet, so live keys are not issued and a request that would send one to CBP is refused with 403. Every API-key response carries Tarifflo-Livemode: true or false.
REST requests send the key in the X-API-Key header:
curl "https://api.tarifflo.com/api/v2/filers" \
-H "X-API-Key: tflo_test_..."The MCP connector also accepts the key as a Bearer token, which suits clients that can only set Authorization:
Authorization: Bearer tflo_test_...OAuth (MCP only)
Claude, ChatGPT and other web MCP clients connect without a key. When the client calls the connector with no credential, it receives an OAuth challenge, opens a Tarifflo sign-in page, and receives an access token for the organization you pick. Tokens last one hour and refresh automatically. See MCP connector.
Scopes
A key must carry the scope an endpoint requires, or the request returns 403. The v2 reference lists the scopes each operation requires.
| Scope | Grants |
|---|---|
classifications | Classification: v1 /api/v1/classifications; on v2, batch classification only (/api/v2/classifications/batch) |
tariff_rates | Tariff rates: v1 /api/v1/tariff-rates; on v2, the rate report (POST /api/v2/sort-sessions/{sortSessionId}/rate-report) |
audit | Pre-audit: /api/v2/audit uploads and runs |
eccn | Export control: /api/v2/export-control |
origin | Country of origin: /api/v2/origin |
entries:write | Entry filing: POST /api/v2/entries |
filing | The filing, sorting, configuration and entry-editing tools of the MCP connector |