Mint a session token for a connection

POST/api/v1/mcp/connections/{key_id}/tokens

Mints a short-lived token for one user that an MCP client sends to one connection's MCP server, at <environment URL>/mcp/v3/connections/{key_id}, without a Virtual MCP server. The token's sub claim is the identifier and its aud claim is that server URL, so the token works only there. Use it when an agent needs the tools of exactly one connection.

This page as markdown Virtual MCP servers overview

Authorization

Authorization: Bearer $TOKEN, an access token from the client credentials grant. See Authentication.

Path parameters

key_idstringrequired

The connection name, as shown in AgentKit > Connections. It's also the last path segment of the connection's MCP server URL.

Body

identifierstringrequired

Your app's ID for the user, the same value you used when the user connected.

expirystring

How long the token lasts, in seconds with an s suffix, such as 1800s. Between 60s and 86400s (24 hours). Defaults to 3600s.

Response 200

expires_atstring

When the token expires: the time it was minted plus expiry.

tokenstring

The session token, a signed JWT. Its sub claim is the identifier and its aud claim is the MCP server URL it works at. Send it as Authorization: Bearer <token> from the MCP client.

Errors

Every error has the same body: code, message and details. See Errors and rate limits.

400Invalid request - key_id or identifier is missing or malformed, expiry is outside the 60s-24h window, or the connection isn't an AgentKit connection. When the user has no active account on the connection yet, Scalekit creates a pending one and still returns a token, so the user can authorize from the MCP client.

404Not found - no active connection with this name exists in the environment.

Request

curl -sS -X POST \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/mcp/connections/gmail/tokens" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user_123",
    "expiry": "1800s"
  }'

1
import os
2

3
import requests
4

5
env_url = os.environ["SCALEKIT_ENVIRONMENT_URL"]
6
token = requests.post(
7
    f"{env_url}/oauth/token",
8
    data={
9
        "grant_type": "client_credentials",
10
        "client_id": os.environ["SCALEKIT_CLIENT_ID"],
11
        "client_secret": os.environ["SCALEKIT_CLIENT_SECRET"],
12
    },
13
).json()["access_token"]
14

15
response = requests.post(
16
    f"{env_url}/api/v1/mcp/connections/gmail/tokens",
17
    headers={"Authorization": f"Bearer {token}"},
18
    json={"identifier": "user_123", "expiry": "1800s"},
19
)
20
response.raise_for_status()
21
result = response.json()

1
const envUrl = process.env.SCALEKIT_ENVIRONMENT_URL!;
2
const tokenResponse = await fetch(`${envUrl}/oauth/token`, {
3
  method: "POST",
4
  body: new URLSearchParams({
5
    grant_type: "client_credentials",
6
    client_id: process.env.SCALEKIT_CLIENT_ID!,
7
    client_secret: process.env.SCALEKIT_CLIENT_SECRET!,
8
  }),
9
});
10
const token = (await tokenResponse.json()).access_token;
11

12
const response = await fetch(`${envUrl}/api/v1/mcp/connections/gmail/tokens`, {
13
  method: "POST",
14
  headers: {
15
    Authorization: `Bearer ${token}`,
16
    "Content-Type": "application/json",
17
  },
18
  body: JSON.stringify({ identifier: "user_123", expiry: "1800s" }),
19
});
20
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
21
const result = await response.json();

Response 200

{
  "token": "[SESSION TOKEN]",
  "expires_at": "2026-10-02T15:00:00Z"
}