Authentication

Exchange an API token for a short-lived session token.

platform.auth Stable free

How to call it

Request schema

Generated from the same validation rules the endpoint runs, so a field cannot be documented without being validated.

POST /v1/auth/session

{
    "type": "object",
    "properties": {
        "audience": {
            "type": [
                "string",
                "null"
            ],
            "enum": [
                "mcp",
                "console"
            ]
        },
        "capabilities": {
            "type": "array",
            "items": {
                "type": "string",
                "maxLength": 64
            }
        },
        "ttl_seconds": {
            "type": [
                "integer",
                "null"
            ],
            "minimum": 60
        }
    },
    "additionalProperties": false
}

Request example

{
    "audience": "mcp",
    "ttl_seconds": 900
}

POST /v1/plan/token

{
    "type": "object",
    "properties": {
        "origins": {
            "type": "array",
            "maxItems": 20,
            "items": {
                "type": "string",
                "maxLength": 255
            }
        },
        "ttl_seconds": {
            "type": [
                "integer",
                "null"
            ],
            "minimum": 60
        }
    },
    "additionalProperties": false
}

Request example

{
    "ttl_seconds": 900,
    "origins": [
        "dispatch.example.com"
    ]
}

Response

What a successful call returns: the schema of `data` and `meta`, with a description of each field, followed by an example response from a real call.

POST /v1/auth/session

Response schema

{
    "description": "A short-lived session token. Send it as `Authorization: Bearer <access_token>` until `expires_at`. It can do only what the key that minted it can do, narrowed to `scopes` when given.",
    "data": {
        "type": "object",
        "properties": {
            "access_token": {
                "type": "string",
                "description": "The session token, `sr_sess_...`. Shown once."
            },
            "token_type": {
                "type": "string",
                "enum": [
                    "Bearer"
                ]
            },
            "expires_in": {
                "type": "integer",
                "description": "Seconds until it expires."
            },
            "expires_at": {
                "type": "string",
                "description": "ISO 8601 with offset."
            },
            "audience": {
                "type": "string",
                "enum": [
                    "mcp",
                    "console"
                ],
                "description": "Who the token is for, as requested."
            },
            "scopes": {
                "type": [
                    "array",
                    "null"
                ],
                "description": "The capabilities it is limited to; null when it carries everything the key may call.",
                "items": {
                    "type": "string"
                }
            }
        },
        "required": [
            "access_token",
            "token_type",
            "expires_in"
        ]
    },
    "meta": {
        "type": "object",
        "properties": {
            "key_id": {
                "type": "string",
                "description": "The API key that minted the session."
            }
        }
    }
}

Response example

{
    "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
    "data": {
        "access_token": "sr_sess_01k8zq3m5n7p9r1t3v5x7z9b2d.Xq7bN2kLm9Pz4Rt8Wv1Yc5Hd3Jf6Gs0Aa2Ee4Uu",
        "token_type": "Bearer",
        "expires_in": 900,
        "expires_at": "2026-10-23T09:42:39-04:00",
        "audience": "mcp",
        "scopes": null
    },
    "meta": {
        "key_id": "sr_live_7Hq2LmX9pR4sT1vW8yZ3nB6c"
    }
}

DELETE /v1/auth/session

Response schema

{
    "description": "The session token sent in `Authorization` is revoked at once.",
    "data": {
        "type": "object",
        "properties": {
            "revoked": {
                "type": "boolean",
                "description": "True once the token is revoked."
            }
        },
        "required": [
            "revoked"
        ]
    }
}

Response example

{
    "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
    "data": {
        "revoked": true
    }
}

POST /v1/plan/token

Response schema

{
    "description": "A plan editor token. Hand it to the plan editor in the browser or the app, which sends it as `Authorization: Bearer <access_token>` to the plan endpoints until `expires_at`, and asks your server for a new one before then. It calls the plan endpoints only, with the plan capabilities of the key; every use checks the key again, so revoking the key or removing its plan capabilities ends the token.",
    "data": {
        "type": "object",
        "properties": {
            "access_token": {
                "type": "string",
                "description": "The plan editor token, `sr_pet_...`. Signed, not stored: it cannot be revoked on its own, only by revoking the key or by its expiry."
            },
            "token_type": {
                "type": "string",
                "enum": [
                    "Bearer"
                ]
            },
            "expires_in": {
                "type": "integer",
                "description": "Seconds until it expires."
            },
            "expires_at": {
                "type": "string",
                "description": "ISO 8601 with offset."
            },
            "scopes": {
                "type": "array",
                "description": "The plan capabilities it may call: `plan.*` for a key that may call everything, else the key's plan entries.",
                "items": {
                    "type": "string"
                }
            },
            "origins": {
                "type": [
                    "array",
                    "null"
                ],
                "description": "The web origins it may be used from, as normalised; null when it is not limited to origins.",
                "items": {
                    "type": "string"
                }
            },
            "fast_path": {
                "type": "object",
                "description": "Present only when the account takes the fast path for plan edits (Open Platform portal, Plan editing path: Fast). The plan editor then sends its calls to `url` (`<url>/recost`, `<url>/move`, ... the same paths as /v1/plan/*) with the same token and the same bodies, and gets the same answers. When the fast path answers 409 USE_STANDARD_PATH, any 5xx, or does not answer in time, the editor repeats the call on /v1/plan/*. Absent: every call goes to /v1/plan/*.",
                "properties": {
                    "url": {
                        "type": "string",
                        "description": "The fast path base address: the map service's plan calls, mirroring /v1/plan/*."
                    }
                },
                "required": [
                    "url"
                ]
            }
        },
        "required": [
            "access_token",
            "token_type",
            "expires_in",
            "expires_at",
            "scopes"
        ]
    },
    "meta": {
        "type": "object",
        "properties": {
            "key_id": {
                "type": "string",
                "description": "The API key that minted the token."
            }
        }
    }
}

Response example

{
    "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
    "data": {
        "access_token": "sr_pet_eyJ2IjoxLCJjaWQiOjEyLCJraWQiOiJzcl9saXZlXzdIcTJMbVg5cFI0c1QxdlcifQ.Xq7bN2kLm9Pz4Rt8Wv1Yc5Hd3Jf6Gs0Aa2Ee4Uu",
        "token_type": "Bearer",
        "expires_in": 900,
        "expires_at": "2026-10-28T09:42:39-04:00",
        "scopes": [
            "plan.*"
        ],
        "origins": [
            "dispatch.example.com"
        ]
    },
    "meta": {
        "key_id": "sr_live_7Hq2LmX9pR4sT1vW8yZ3nB6c"
    }
}

What it costs

Never billed, and never disable-able.

Every billable response carries a billing block with the unit, the quantity and how the quantity was derived.

Errors it can return