Skip to content

Verifying User Identity

When a superglue tool calls your API, you sometimes need to know which user triggered the run, and you need proof, not just a header anyone could set. superglue provides two runtime variables for this:

  • <<sg_auth_email>>: the plaintext email of the user who triggered the run. Simple, but spoofable by anyone who can send you an HTTP request.
  • <<sg_auth_jwt>>: a short-lived JWT signed by superglue that encodes the triggering user’s identity. Your endpoint verifies the signature against superglue’s public keys, giving you cryptographic proof.

Both resolve automatically at execution time. In scheduled runs they resolve to the schedule creator.

Using sg_auth_jwt in a tool

Section titled “Using sg_auth_jwt in a tool”

Reference the variable anywhere in a step config, typically a header:

Authorization: Bearer <<sg_auth_jwt>>

or

X-Superglue-User: <<sg_auth_jwt>>

The token is only minted when a tool actually references it. If the run has no associated user (for example an org-level API key), the run fails with a resolution error telling you to run the tool as a signed-in user or with a user-linked API key.

Token contents

Section titled “Token contents”

The token is an EdDSA-signed JWT with these claims:

Claim Value
iss The superglue web app origin
sub The superglue user id of the triggering user
email The user’s email
orgId The organization the run executed in
token_use Always "sg_outbound_identity"
iat/exp Issued-at and expiry; tokens are valid for 1 hour

Verifying the token

Section titled “Verifying the token”

Outbound identity tokens are signed with a dedicated keypair, separate from superglue’s session keys. Fetch the public key from the outbound JWKS endpoint on the web app origin (https://app.superglue.cloud/api/auth/outbound-jwks on superglue Cloud, or your own deployment’s app URL when self-hosting), then verify:

  1. The signature, against the JWKS
  2. exp (not expired)
  3. iss equals the superglue origin you expect
  4. token_use equals "sg_outbound_identity" (required)

With jose:

import { createRemoteJWKSet, jwtVerify } from "jose";


const jwks = createRemoteJWKSet(new URL("https://app.superglue.cloud/api/auth/outbound-jwks"));


const { payload } = await jwtVerify(token, jwks, {
  issuer: "https://app.superglue.cloud",
});
if (payload.token_use !== "sg_outbound_identity") {
  throw new Error("Not a superglue outbound identity token");
}


// payload.sub, payload.email, payload.orgId identify the triggering user