Skip to main content
An API connector lets the workspace’s AI, rules and tiles call your REST API. When the person asking is one of your embedded users, the call must be made as them, never as someone else. You choose how Upsolve does that when you add the connector: “How should Upsolve call your API for each user?” Whenever the agent, a rule or a tile calls your API for a user, Upsolve attaches a fresh five-minute token signed with your project’s private key. The token names the user with the same externalIds your backend already sends to embed-token. Your API checks the signature against Upsolve’s published public keys, then treats the request as that user.
  • Nothing to host and no secret to keep: the keys that check the token are public.
  • Nothing for your users to do, and background work just works: Upsolve can sign a token for a rule at 3 a.m. with nobody signed in.
  • One issuer per Upsolve project, so another Upsolve customer can never mint a token your API accepts.
The token
When you choose it, the connector shows your issuer, JWKS URL and audience, and three ways to set up the check: a prompt to paste into your coding agent, snippets in five languages, and steps for Supabase, Auth0 and Clerk. Then Check calls one of your endpoints with a valid token and two your API must refuse, and tells you what to fix. Verify Upsolve tokens has the full rules and snippets. A user with no externalId (for example a member of your Upsolve organization who is not one of your embedded users) gets none of the connector’s tools: “Your account has no external id, so Upsolve can’t name you to Acme Billing.” The same goes for a user missing a property you add as a claim.

With one API key, and a user binding

Keep one API key on the connector. It is stored encrypted and only ever sent to your API’s base URL. A binding tells Upsolve which parameter names the user, and which property supplies its value: The properties are the ones you pass to POST /v1/api/projects/embed-token in organization.properties and user.properties, the same ones row-level security reads. If your API wants the account id in a header, send it once at sign-in and bind it:
embed-token (excerpt)
Binding
How it behaves:
  • 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.
Upsolve enforces the binding; your API does not see who is asking. It is the same trust as giving Upsolve database credentials with row-level security: the key can act for any account, and Upsolve only ever sends the caller’s own.

OAuth

Enter your OAuth client ID and secret, the authorization and token endpoints (prefilled from your OpenAPI spec when it declares them) and the scopes. Each user signs in once in a popup. Upsolve stores their tokens encrypted and refreshes them, so rules and scheduled work keep running. If a refresh is refused, the user sees “needs to be reconnected” and their rules pause until they connect again. The client secret is only sent to your token endpoint.

When your API can only accept its own tokens

Choose Your backend hands out tokens (the token callback) when your API cannot check a token it did not issue and has no server key. Upsolve asks your endpoint for a token each time it needs one for a user. If your API can check a JWT, As the signed-in user is less work: there is nothing to host. Set it up in this order. The connector walks you through it after you save it.
  1. Save the connector without a URL. Upsolve makes its signing secret (upsk_...) when you save. It is always available on the connector: Reveal, Copy, or Copy env line for UPSOLVE_CALLBACK_SECRET=.... Until the connector has a URL nobody can use it, and it says Finish setup.
  2. Build the endpoint. Copy the prompt into your coding agent inside your backend, or start from the reference handlers below. Read the secret from UPSOLVE_CALLBACK_SECRET and never log it. A good place is next to your embed-token route.
  3. Test it locally with the script below, before you deploy.
  4. Go live. Add the URL. Upsolve checks it before saving: a correctly signed request for you must get a token, and a request with a wrong signature must get a 4xx. A failure says what to fix (404: the path; 401 on the good request: the secret, or a body that was parsed before it was checked; a timeout: the endpoint is unreachable or slow; a 2xx on the bad signature: your endpoint isn’t checking the signature). Save anyway saves it regardless.
You can rotate the secret from the connector, which invalidates the old one at once. Send test request runs the same check against the saved URL. The token itself is never shown. By default the token is sent as Authorization: Bearer <token>. Token goes in changes the header and the text before the token.

Test it locally

Save this as test-callback.mjs (no dependencies, Node 18 or later), start your server, and run it with a user id your app knows:
It sends a correctly signed request (expects 200 and a token), a request with a wrong signature, and a correctly signed one from 10 minutes ago (each expects a 4xx), and prints a checklist.
test-callback.mjs

The request

  • 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 and expiresIn (seconds, up to 7 days) are required. tokenType defaults to Bearer. The token is sent as Authorization: Bearer <token> unless you configured another header and prefix. The answer must be JSON under 64 KB.

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

Upsolve keeps each token in memory for its user and connector until 60 seconds before it expires (at most 24 hours), so your endpoint is called roughly once per token lifetime per user. Simultaneous requests for one user share a single call. Tokens are never written to a database or a log, and rotating the secret clears them.

Samples

Both samples are complete, tested endpoints you can copy: examples/api-connector-token-callback has a Node (Express) and a Python (FastAPI) version, with the contract in its README. The verification function in each:
Replace the sample’s mintTokenFor / mint_token_for stub with your own user lookup and token issuer.