curl https://api.tracklysms.com/api/v2/auth/whoami \
-H "X-Api-Key: trk_your_api_key"
{
"account": {
"id": 262,
"name": "Mom and Pop's Pizza",
"status": "active",
"plan": "paid",
"parent_account_id": null
},
"api_key": {
"id": "66f1c2a9b8e4d3f0a1b2c3d4",
"name": "hermes-agent (sandbox)",
"status": "active",
"key_prefix": "trk_a1b2",
"sandbox": true,
"expires_at": "2026-12-01T00:00:00Z",
"lifecycle_denial": null,
"created_at": "2026-09-03T18:20:11.000000Z",
"last_used_at": "2026-09-03T18:25:40.000000Z",
"send_policy": {
"list_numbers": ["+18005551234"],
"daily_send_cap": 50,
"sends_today": 0
}
}
}
{ "error": "Account is suspended", "code": "account_suspended" }
V2 API Reference
Who Am I
Resolve which account and API key a request authenticates as, and whether the key is a sandbox key.
GET
/
v2
/
auth
/
whoami
curl https://api.tracklysms.com/api/v2/auth/whoami \
-H "X-Api-Key: trk_your_api_key"
{
"account": {
"id": 262,
"name": "Mom and Pop's Pizza",
"status": "active",
"plan": "paid",
"parent_account_id": null
},
"api_key": {
"id": "66f1c2a9b8e4d3f0a1b2c3d4",
"name": "hermes-agent (sandbox)",
"status": "active",
"key_prefix": "trk_a1b2",
"sandbox": true,
"expires_at": "2026-12-01T00:00:00Z",
"lifecycle_denial": null,
"created_at": "2026-09-03T18:20:11.000000Z",
"last_used_at": "2026-09-03T18:25:40.000000Z",
"send_policy": {
"list_numbers": ["+18005551234"],
"daily_send_cap": 50,
"sends_today": 0
}
}
}
{ "error": "Account is suspended", "code": "account_suspended" }
Returns the account and key behind the calling credentials. Use it as the first call in any integration: it confirms the key works, names the account it belongs to, and reports the server’s own decision on whether the key is a sandbox key. Read-only, no side effects beyond the key’s last-used timestamp.
api_key.sandbox is authoritative. A key created with Sandbox mode on is a sandbox key whatever its value looks like, so do not infer mode from the trk_ prefix.Response Fields
object
Show account
Show account
object
Show api_key
Show api_key
string
API key ID, as listed in the dashboard.
string
The key’s name.
string
active, or pending_deletion for a rotated key. Check lifecycle_denial for an expired grace window while lifecycle enforcement is rolling out. A paused or revoked key never reaches this endpoint.string
The first characters of the key value, for matching against a masked listing.
null for keys created before prefixes were recorded.boolean
true when requests with this key are simulated: nothing is delivered and nothing is billed.string
Expiry (ISO-8601, UTC);
null when the key does not expire.string
expired_api_key or key_grace_expired when the key is past its expiry or its rotation grace. Such a key is refused with 401 once key-lifecycle enforcement is on; until then it still authenticates, so treat any non-null value as “rotate now”. null while the key is in good standing.string
Creation time (ISO-8601, UTC).
string
The most recent authenticated use before this call (ISO-8601, UTC). The current call is recorded after the response and debounced to about a minute, so a key’s first ever request answers
null and a burst of calls reports the burst’s first.object
The send restrictions attached to this key. Set them when creating the key (
resourceConstraints.list_numbers, dailySendCap) in the dashboard or through the partner key-mint endpoint.Show send_policy
Show send_policy
boolean
When true, direct sends and send-enabling operations are blocked. Use the SMS approval workflow; email and OTP have no pending-send workflow.
string[]
Sending-list numbers (E.164) this key may send from. Empty means any list on the account. A send from any other list, or a schedule whose source lists include another list, is refused with
403 list_not_allowed_for_key.integer
Maximum counted live sends per UTC day through the four SMS send endpoints;
null when uncapped. Sandbox and OTP sends do not count. Capped keys cannot create or edit schedules; see schedule restrictions. When reached, sends are refused with 429 daily_cap_exceeded. Known construction or storage failures before publication attempt to refund a confirmed reservation. If the refund fails or cannot be confirmed, allowance may remain used for the original UTC day even though the message was not published. An uncertain quota reservation may also remain charged when the send is refused. Once publication starts, errors retain quota because delivery may have occurred. A rotated key and its replacement share one counter.integer
Sends counted against the cap today (UTC), including publication attempts with uncertain outcomes;
null when the key is uncapped or the counter is unavailable.Errors
| HTTP Status | Error Code | Description |
|---|---|---|
| 401 | invalid_credentials | The key is missing, unknown, paused, or revoked. An expired key is also refused once key-lifecycle enforcement is on; before that it authenticates and reports lifecycle_denial. |
| 403 | account_suspended | The account, or its umbrella parent, is suspended. The parent check is cached for about a minute and is skipped if the parent cannot be looked up, so a parent suspension can take a minute to reflect here. |
| 503 | send_cap_unavailable | The key’s stored daily cap or list-policy metadata is invalid. Malformed restrictions are never reported as unrestricted access. Contact support to correct the policy. |
Examples
curl https://api.tracklysms.com/api/v2/auth/whoami \
-H "X-Api-Key: trk_your_api_key"
{
"account": {
"id": 262,
"name": "Mom and Pop's Pizza",
"status": "active",
"plan": "paid",
"parent_account_id": null
},
"api_key": {
"id": "66f1c2a9b8e4d3f0a1b2c3d4",
"name": "hermes-agent (sandbox)",
"status": "active",
"key_prefix": "trk_a1b2",
"sandbox": true,
"expires_at": "2026-12-01T00:00:00Z",
"lifecycle_denial": null,
"created_at": "2026-09-03T18:20:11.000000Z",
"last_used_at": "2026-09-03T18:25:40.000000Z",
"send_policy": {
"list_numbers": ["+18005551234"],
"daily_send_cap": 50,
"sends_today": 0
}
}
}
{ "error": "Account is suspended", "code": "account_suspended" }