Skip to main content
The Vybe User Token (VUT) is a short-lived, cryptographically signed JWT that identifies the current user in a deployed app. It is the mechanism Vybe uses to pass user identity from the authentication layer to your app and, subsequently, to any Vybe APIs your app calls.
You do not need to manage the VUT directly in most cases. Vybe handles token minting, injection, and validation automatically. This page is for advanced users who need to understand the authentication flow for custom server-side logic.

​
How it works

The VUT is part of every authenticated request to a deployed app:
1

User visits a deployed app

The user navigates to <app-slug>-<org-slug>.vybe.build and is authenticated through Vybe’s session system.
2

Vybe mints a VUT

The Vybe middleware creates a new VUT for this request. The token contains claims that identify the user, the app, and the token’s validity window.
3

Token is injected as a header

The VUT is added to the request as the x-vybe-user-token header before the request is forwarded to your app.
4

Your app forwards the VUT

When your app makes API calls to Vybe services (fetching integration data, running data queries, etc.), it includes the VUT in the request headers. This tells Vybe which user is making the request.
5

Vybe validates the token

Vybe verifies the token’s signature, checks that it has not expired, and confirms that the user has access to the requested resource.

​
Token details

PropertyValue
FormatStandard JWT (RFC 7519)
AlgorithmED25519 (EdDSA)
Lifetime13 minutes
Deliveryx-vybe-user-token request header

​
Why ED25519

Vybe uses ED25519 (Edwards-curve Digital Signature Algorithm) for signing tokens. Compared to RSA or HMAC-based JWT signatures, ED25519 offers:
  • Faster signing and verification — important for low-latency request handling
  • Smaller signatures — 64 bytes vs. 256+ bytes for RSA, reducing header size
  • Strong security — 128-bit security level, equivalent to RSA-3072

​
Token claims

The VUT contains the following standard JWT claims:
ClaimNameDescription
subSubjectThe user’s unique ID
audAudienceThe app’s unique ID — ensures the token is only valid for the intended app
iatIssued AtUnix timestamp of when the token was minted
expExpirationUnix timestamp of when the token expires (13 minutes after issuance)
issIssuerIdentifies Vybe as the token issuer

​
Two-factor API authentication

Vybe uses two credentials together to authenticate API calls from your app:
CredentialIdentifiesScope
VYBE_SERVER_SECRETThe appApp-level resources
x-vybe-user-token (VUT)The userUser-level resources

​
When you need both

App-level resources require only the server secret. These are resources that belong to the app itself, not to any specific user:
  • Shared integration connections
  • Organization-wide data queries
  • App configuration
User-level resources require both the server secret and the VUT. These are resources tied to a specific user:
  • Personal integration accounts (a user’s own Slack connection)
  • User-specific data
  • Actions performed on behalf of a user

​
Example: API call with both credentials

// app/api/my-slack-messages/route.ts
export async function GET(request: Request) {
  const response = await fetch('https://api.vybe.build/v1/integrations/slack/messages', {
    headers: {
      'x-vybe-server-secret': process.env.VYBE_SERVER_SECRET!,
      'x-vybe-user-token': request.headers.get('x-vybe-user-token')!,
    },
  });

  const messages = await response.json();
  return Response.json(messages);
}
In this example, the server secret authenticates the app and the VUT identifies which user’s Slack messages to fetch.

​
Key rotation

Vybe uses a blue/green key rotation strategy to rotate signing keys without downtime.

​
How it works

  1. Two key slots — Vybe maintains two signing key slots (blue and green). Both are always active for token validation.
  2. One active for minting — At any given time, only one slot is used to sign new tokens. For example, the blue key signs all new VUTs.
  3. Rotation — When it is time to rotate, Vybe switches minting to the green key. New tokens are signed with the green key.
  4. Graceful expiry — Tokens signed with the old blue key remain valid until they expire (up to 13 minutes). Both keys are accepted for validation during this window.
  5. Cleanup — After all old tokens have expired, the blue key slot is replaced with a fresh key, ready for the next rotation.

​
Why this matters

  • Zero downtime — Key rotation never invalidates active tokens. Users experience no interruption.
  • No coordination required — Your app does not need to do anything during a rotation. Vybe handles validation of both old and new keys automatically.
  • Short exposure window — Because tokens live for only 13 minutes, the overlap window during rotation is brief.

​
Token lifecycle

Here is the complete lifecycle of a VUT from creation to expiration: 
User visits app
     │
     ▼
Vybe authenticates session (cookie)
     │
     ▼
Vybe checks app access (role + grants)
     │
     ▼
Vybe mints VUT (signed with active key)
     │
     ▼
VUT injected as x-vybe-user-token header
     │
     ▼
App receives request with user context
     │
     ▼
App calls Vybe API with VUT + server secret
     │
     ▼
Vybe validates VUT signature + expiration
     │
     ▼
API returns user-scoped data
     │
     ▼
VUT expires after 13 minutes

​
Frequently asked questions

Yes. The VUT is a standard JWT, so you can decode it using any JWT library. However, you should not validate it yourself — let Vybe handle validation when you pass it in API calls. Decoding the token can be useful for reading the sub claim (user ID) without making an API call.
The VUT is validated when your app makes an API call to Vybe, not when the original request was received. If a VUT expires mid-request, the API call will return a 401 error. For long-running operations, make your Vybe API calls as early as possible in the request lifecycle.
No. The VUT is only valid for Vybe APIs. Third-party services will not recognize or accept it. To call third-party APIs, use the credentials provided through the Vybe integration system.
No. The VUT is generated per-request, injected as a header, and discarded after the response. It is not stored in cookies, local storage, or any database.

​
Security context

The VUT is part of Vybe’s defense-in-depth approach to API authentication:
  • Security middleware validates the session and mints the VUT before the request reaches your app — this middleware is hand-written infrastructure code, never AI-generated
  • Server secret authenticates the app itself, ensuring requests come from legitimate Vybe applications
  • VUT authenticates the user, enabling user-scoped data access and audit trails
  • Short lifetime (13 minutes) limits exposure if a token is somehow intercepted
  • Audience binding prevents a token minted for one app from being used against another
Together, these layers ensure that every API call is authenticated at both the app and user level.

​
What’s next