Step-up Session

Configure step-up authentication sessions for sensitive actions. Step-up requires users to re-authenticate (e.g., passkey, TOTP, or hardware key) before accessing high-privilege operations

What the Step-up Session Panel Does

The Step-up Session panel lets you:

• Configure when step-up authentication is required
• Set session duration for elevated privileges
• Define which actions trigger step-up prompts

Prerequisites

• Active Transcodes project
• RBAC roles configured (for role-based step-up)

Opening the Step-up Session Panel

How Step-up Sessions Work

A step-up session is a temporary elevation of a user’s authentication level. When a user attempts a sensitive action, Transcodes prompts for additional authentication before granting access.

Flow:

1. User is already authenticated with a standard session
2. User attempts a sensitive action (e.g., changing account settings)
3. Transcodes prompts for re-authentication (passkey, TOTP, or hardware key)
4. Upon success, a temporary elevated session is created
5. The elevated session expires after the configured duration
6. User returns to standard session level

Temporary Session Lifecycle

Standard Session (long-lived)
    │
    ├── User triggers sensitive action
    │
    ├── Re-authentication prompt
    │
    ├── ✅ Step-up Session created (short-lived)
    │   ├── Elevated access granted
    │   ├── Timer starts (e.g., 5 minutes)
    │   └── Session expires → back to standard
    │
    └── Standard Session continues

Key characteristics:

• Step-up sessions are scoped to the action or resource that triggered them
• The elevated session token is separate from the standard session token
• Expiration is enforced server-side regardless of client behavior

Configuration Options

Configure step-up session behavior in the Step-up Session panel:

Setting the Duration

Choose a duration that balances security and usability:

• 1-5 minutes: High-security operations (payments, key management)
• 15-30 minutes: Moderate-security operations (settings changes)
• 60 minutes: Low-friction operations (viewing sensitive data)

Integration Example

Use the Transcodes SDK to trigger step-up authentication in your application. The modal returns a temporary session id (sid) — never trust it on the client; forward it to your backend for verification.

// Client — request step-up and forward the sid to your backend
async function handleDeleteAccount(userId: string) {
  const result = await transcodes.openAuthIdpModal({
    resource: 'account',
    action: 'delete',
    forceStepUp: true,
  });
 
  if (!result.success || !result.payload[0]?.success) return;
 
  const stepUpSid = result.payload[0].sid;
 
  await fetch(`/api/users/${userId}`, {
    method: 'DELETE',
    headers: {
      Authorization: `Bearer ${await transcodes.token.getAccessToken()}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ stepUpSid }),
  });
}

Verifying sid server-side

The sid returned by openAuthIdpModal is a one-time temporary session id that lives only on the Transcodes side. Your backend must call the Transcodes API to confirm the step-up actually succeeded for the right (member, resource, action) before performing the sensitive operation.

• Endpoint: GET https://api.transcodesapis.com/v1/auth/temp-session/step-up/{sid}
• Header: x-transcodes-token: <AUTH_API_TOKEN> — a server-only JWT issued from the Transcodes Console (different from TRANSCODES_TOKEN used by the MCP server). Store it as TRANSCODES_AUTH_API_TOKEN (or similar) and never expose it to the browser.
• Response: 200 with a payload describing the verified step-up; non-200 means invalid or expired.

// app/api/users/[id]/route.ts (Next.js App Router)
import { NextResponse } from 'next/server';
 
const AUTH_API_TOKEN = process.env.TRANSCODES_AUTH_API_TOKEN!;
 
export async function DELETE(
  req: Request,
  { params }: { params: { id: string } },
) {
  const { stepUpSid } = await req.json();
 
  if (!stepUpSid) {
    return NextResponse.json(
      { error: 'Missing step-up session id' },
      { status: 400 },
    );
  }
 
  const response = await fetch(
    `https://api.transcodesapis.com/v1/auth/temp-session/step-up/${stepUpSid}`,
    {
      headers: {
        'x-transcodes-token': AUTH_API_TOKEN,
      },
    },
  );
 
  if (!response.ok) {
    return NextResponse.json({
      logId: crypto.randomUUID(),
      success: false,
      statusCode: response.status,
      payload: null,
      error: 'Failed to verify step-up session',
    });
  }
 
  const data = await response.json();
  // data.payload[0] => { project_id, member_id, action, role }
  // Optional: assert data.payload[0].action === 'delete' and member_id matches the caller.
 
  await deleteUser(params.id);
  return NextResponse.json({ ok: true });
}

Example successful response:

{
  "logId": "01KPP893GSV54TKVST53MV7BB1",
  "success": true,
  "statusCode": 200,
  "payload": [
    {
      "project_id": "ca3da7ff8dd4391d8d80ad01",
      "member_id": "ca3db8488dd4391d8d80ad04",
      "action": "read",
      "role": "admin"
    }
  ],
  "error": null
}

Related

• Step-up Auth - Implement step-up authentication in your app
• RBAC - Role-based access control
• Modal API - openAuthIdpModal for step-up flows