Verifying User Identity

When a superglue tool calls your API, you sometimes need to know which user triggered the run. You also need proof, because anyone could set a plain header.

Choose a variable

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.

Add sg_auth_jwt to 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.

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

Verify 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. On superglue Cloud, this is https://app.superglue.cloud/api/auth/outbound-jwks. When self-hosting, use your own deployment’s app URL.

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

!

The token is a real identity assertion: anyone holding it can prove “this user triggered a superglue request” for up to an hour. Only send it to endpoints you trust, the same caveat as any bearer credential. It proves who triggered the request, but it is not bound to the request method, URL, or body.

FAQ

Which user do the variables use in a scheduled run?

In scheduled runs, both variables resolve to the schedule creator.

What happens when the run has no user?

If the run has no associated user (for example an org-level API key), the run fails with a resolution error. The error tells you to run the tool as a signed-in user or with a user-linked API key.