All documentation
Documentation
POST
/sdk/v1/agent/tokenTrades the SDK key for an agent token for one person of yours, valid for 15 minutes. Requires the key's agent:read scope and the assistant switched on for the organization. Your backend sends the token to the assistant and to its MCP reads; it never reaches a browser.
Base URL
| Environment | URL |
|---|---|
| Production | https://infra.usegrade.com/api/email |
| Sandbox | https://infra-sandbox.usegrade.com/api |
Headers
Required on every request, as on every SDK v1 route.
| Header | Value |
|---|---|
X-Application-Id |
Your SDK application ID. |
X-Api-Key |
Your SDK API key secret. |
Content-Type |
application/json |
Request body
Who is asking.
| Property | Type | Required | Description |
|---|---|---|---|
end_user |
string, matching ^[\w-]{1,128}$ |
Yes | Your id for the person asking: letters, digits, _ or -. Opaque to Grade, never an email. |
A property this table does not name is refused.
{
"end_user": "user_8f3a2c"
}
Responses
200
The agent token.
| Property | Type | Required | Description |
|---|---|---|---|
token |
string | Yes | The agent token, sent as Authorization: Bearer <token>. |
expires_at |
string (date-time) | Yes | |
api_version |
1 |
Yes |
400
The body is not { "end_user": string } with a valid id.
| Property | Type | Required | Description |
|---|---|---|---|
success |
false |
Yes | |
code |
INVALID_REQUEST |
Yes | |
message |
string | Yes |
403
The assistant is not open to this organization.
| Property | Type | Required | Description |
|---|---|---|---|
success |
false |
Yes | |
code |
one of AGENT_DISABLED, AGENT_IMPERSONATION_ONLY |
Yes | |
message |
string | Yes |
503
The assistant is not configured on this environment.
| Property | Type | Required | Description |
|---|---|---|---|
success |
false |
Yes | |
code |
AGENT_UNCONFIGURED |
Yes | |
message |
string | Yes |
