Let Upsolve act as your users

​

Server key and user binding (recommended)

{
  "organization": { "externalId": "acme", "properties": { "account_id": "acct_4821" } },
  "user": { "externalId": "u_123", "properties": { "external_user_id": "u_123" } }
}

{ "in": "header", "name": "X-Account-Id", "source": "projectOrganization", "property": "account_id" }

• The model never chooses the user. A bound parameter is removed from the tool’s schema and set by Upsolve on every call. If the model supplies one anyway, it is dropped.
• Properties are read on the server, not from the token in the browser, so a user cannot change them.
• It fails closed. A user who has no value for a bound property gets none of the connector’s tools, with the reason shown (“Your account has no account_id.”).
• Operations that do not take every bound parameter are hidden, unless you mark them global (a plan list, a lookup table). A server key can act for any account, so a call without its binding could read across customers.
• The property must be a string, number or boolean. An empty or missing value counts as missing.

​

OAuth

​

Token callback

​

The request

POST https://api.example.com/upsolve/token
X-Upsolve-Timestamp: 1761200000
X-Upsolve-Signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>
Content-Type: application/json
User-Agent: Upsolve-Token-Callback/1.0

{"externalUserId":"u_123","externalOrganizationId":"acct_4821","projectUserId":"…","projectId":"…","workspaceId":"…","scopes":["invoices:read"],"requestId":"…"}

• externalUserId and externalOrganizationId are the externalId values you sent to embed-token. They are null for a member of your Upsolve organization who is not one of your embedded users.
• scopes are the scopes you configured on the connector.
• The timestamp is Unix seconds. The signature is the lowercase hex HMAC-SHA256 of <timestamp>.<raw body>, keyed with the callback secret.

​

Your response

{ "accessToken": "…", "expiresIn": 900, "tokenType": "Bearer" }

​

What to check on your side

1. Verify the signature over the raw body before parsing it. Re-serialised JSON will not match.
2. Reject timestamps more than 300 seconds from your clock.
3. Compare in constant time.
4. Look the user up by externalUserId. If you do not know them, or they are not entitled to this API, answer with a 4xx.
5. Return a short-lived token for that user only.

​

Failures

​

Caching

​

Samples

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyUpsolveSignature({ secret, timestamp, signature, rawBody, nowSeconds }) {
  if (!/^\d{1,12}$/.test(timestamp ?? "")) return false;
  if (Math.abs(nowSeconds - Number(timestamp)) > 300) return false;
  const match = /^v1=([0-9a-f]{64})$/.exec(signature ?? "");
  if (!match) return false;
  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody) // the Buffer from express.raw(), not parsed JSON
    .digest();
  return timingSafeEqual(Buffer.from(match[1], "hex"), expected);
}

import hashlib, hmac, re, time

def verify_upsolve_signature(secret, timestamp, signature, raw_body: bytes) -> bool:
    if not re.fullmatch(r"[0-9]{1,12}", timestamp or ""):
        return False
    if abs(time.time() - int(timestamp)) > 300:
        return False
    match = re.fullmatch(r"v1=([0-9a-f]{64})", signature or "")
    if not match:
        return False
    expected = hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(match.group(1), expected)  # raw_body = await request.body()