Every inbox DimeBox provisions comes with exactly one credential that controls reading it: a read_token, returned once in the 201 response at creation time, in the shape inbox_.... Not a password. Not a username and password pair. A single opaque string, shown exactly once, that you either save or don't.
The read token has one job: it's passed as the X-Inbox-Token header on the two read endpoints.
curl https://dimebox.app/api/inboxes/acme-support/messages \
-H 'X-Inbox-Token: inbox_...'
curl https://dimebox.app/api/inboxes/acme-support/messages/03d02b6a-30c4-43ba-877c-aefbe560d159 \
-H 'X-Inbox-Token: inbox_...'Without a valid token, both routes return 401. There's no fallback auth, no "forgot your token" link, and reading a mailbox is the only thing gated by it — sending from the inbox and receiving mail into it are gated by payment instead, not by this token. That split matters: losing the read token doesn't stop the inbox from working, it stops you from seeing what's in it. Losing your inbox read token walks through that scenario in full.
A username/password pair, or an API key tied to an account, assumes there's an account to tie it to — something with a recovery email, a support channel, a "reset" flow. DimeBox inboxes don't have accounts. There's no signup, so there's nothing to log into. A bearer token that proves possession, rather than identity, is the natural fit: whoever holds the string can read the mailbox, full stop. Who owns an agent's inbox covers the ownership model this implies in more detail.
This is also a deliberately different kind of credential from the ones that gate payment. An x402 signature or a wallet secret proves you're willing to pay for an action right now; the read token proves you're allowed to see what's already happened. x402 vs API keys looks at that distinction from the payment side — this is the read side of the same "agents need different credentials than humans" argument.
DimeBox doesn't keep a plaintext copy of your read token sitting in a database waiting to be looked up and re-sent to you. What's stored is a hash of it, which is enough to verify a token presented later but not enough to reconstruct the original string. That's why there's no "resend my token" support request that could possibly be fulfilled — the plaintext simply isn't retained anywhere to resend. Hashing secrets instead of storing them covers the reasoning behind that choice across DimeBox's token model generally, not just read tokens.
If you set a webhook_url when provisioning an inbox, the response also includes a webhook_secret — shown once, in the same response, next to the read token. It's used to verify that inbound webhook notifications actually came from DimeBox, via an HMAC signature on each request. Treat it with the same care: write it to durable storage immediately, because it isn't shown again either. The webhook notifications guide covers verification in detail.
Because the token is shown exactly once, the only safe pattern is to persist it the moment the provisioning call returns, before doing anything else with the response. A few things worth building in from the start:
For the provisioning call that hands you this token in the first place, see how to provision an inbox in one API call.
Call either read endpoint without an X-Inbox-Token header, or with one that doesn't match the inbox in the URL, and the response is a 401. There's no partial response, no degraded "preview" of the inbox — either the token checks out and you get the full message list, or it doesn't and you get nothing. A message_id is also looked up scoped to the inbox in the URL, so a valid token for one inbox won't let you read a different inbox's message even if you happen to know its ID — that lookup 404s instead of leaking anything across inboxes.
It's easy to conflate the read token with a wallet secret, since both are opaque bearer strings DimeBox hands you once. They're not interchangeable. A wallet secret, passed as Authorization: Bearer <wallet_secret>, authorizes spending — it's how you pay for drafting, sending, claiming a name, or priority receive, without going through the x402 signing flow. A read token authorizes nothing financial at all; it only unlocks reading one specific inbox's message history. An agent could hold a wallet secret and no read token — able to pay for actions, unable to read any inbox's mail — or a read token and no wallet — able to read one inbox, unable to pay for anything. Keeping them separate is deliberate: compromising one doesn't hand over the other.