Authentication
Every request except GET /v1/health needs an API key, sent as a bearer token:
GET /v1/dt-score?dot_number=1000001 HTTP/1.1
Host: sandbox-api.dollartraq.com
Authorization: Bearer dt_test_9fQ2m…
Requests go over HTTPS only.
Keys belong to one environment#
| Key starts with | Works at | Returns |
|---|---|---|
dt_test_ |
https://sandbox-api.dollartraq.com |
Sandbox test carriers |
dt_live_ |
https://api.dollartraq.com |
Real carriers, counted against your quota |
A key sent to the other environment is refused with 401 wrong_environment_key, so a test key can never reach live data by mistake, and a live key cannot run up your quota from a test suite.
Your account can hold several keys in each environment, for example one per server or service. They share your account's rate limit and monthly quota.
Keep keys secret#
A key acts as your account. Anyone who has it can use your quota.
- Keep keys on your servers: in environment variables or a secrets manager, never in source control.
- Never call the API from a browser or a mobile app. Call it from your backend and pass the result on.
- Use a separate key for each system, so you can revoke one without stopping the others.
DollarTraq stores only a one-way hash of each key and cannot show it to you again. If you lose a key, ask for a new one.
Rotate or revoke a key#
To rotate a key without downtime:
- Ask your DollarTraq contact for a new key for the same environment.
- Deploy the new key everywhere the old one is used.
- Ask for the old key to be revoked. From then on it gets
401 revoked_api_key.
If a key may have leaked, ask for it to be revoked straight away, then issue a replacement.
Authentication errors#
| Status | Code | Means |
|---|---|---|
| 401 | missing_api_key |
No Authorization: Bearer header |
| 401 | invalid_api_key |
The key is malformed or unknown |
| 401 | wrong_environment_key |
A dt_test_ key on live, or a dt_live_ key on the sandbox |
| 401 | revoked_api_key |
The key has been revoked |
| 403 | account_suspended |
The account's access is paused. Contact DollarTraq |
Every 401 carries a WWW-Authenticate: Bearer header.