Modal API
⚡ 10 min readThe Transcodes SDK provides three modal methods for authentication. All modals return Promises with standardized ApiResponse objects. Project administration (members, roles, resources, audit logs) is done through the Transcodes MCP server, not a fourth modal.
Overview
| Modal | Purpose | When to Use |
|---|---|---|
openAuthLoginModal() | Login & Signup | Initial member authentication |
openAuthConsoleModal() | Account Management | Profile, Passkey, MFA settings |
openAuthIdpModal() | Step-up Auth (IDP) | Sensitive operations (2FA) |
About projectId parameter: In almost all cases, the projectId is
automatically provided from the SDK initialization configuration. If you
explicitly provide it in the modal method parameters, it will override the
automatically provided value
Methods
openAuthLoginModal()
Opens the integrated login and signup modal. New users create accounts via email verification, while existing users sign in with Passkey or Email OTP
transcodes.openAuthLoginModal(params: {
projectId?: string;
/** Whether to send Slack webhook notifications on login success/failure when true. Default: false */
webhookNotification?: boolean;
}): Promise<ApiResponse<AuthResult[]>>Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | No | Project ID (automatically provided in most cases) |
webhookNotification | boolean | No | Send Slack webhook on login success/failure. Default: false |
Returns: Promise<ApiResponse<AuthResult[]>>
Example:
const result = await transcodes.openAuthLoginModal({
projectId: '{YOUR_PROJECT_ID}',
});
if (result.success) {
const { member } = result.payload[0];
console.log('Logged in:', member?.email);
}openAuthConsoleModal()
Opens the account management console. Authenticated members can manage their profile, Passkeys, and MFA settings
transcodes.openAuthConsoleModal(params?: {
projectId?: string;
}): Promise<ApiResponse<null>>Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | No | Project ID (automatically provided) |
Returns: Promise<ApiResponse<null>>
Example:
await transcodes.openAuthConsoleModal({
projectId: '{YOUR_PROJECT_ID}',
});openAuthIdpModal()
Opens the IDP (Internal Identity Provider) modal for step-up authentication. Use for sensitive operations that require re-authentication (e.g., MFA)
transcodes.openAuthIdpModal(params: IdpOpenParams & { projectId?: string }): Promise<ApiResponse<IdpAuthResponse[]>>Parameters (IdpOpenParams):
| Parameter | Type | Required | Description |
|---|---|---|---|
resource | string | Yes | RBAC resource key (e.g. 'users', 'revenue') |
action | 'create' | 'read' | 'update' | 'delete' | Yes | CRUD action type |
forceStepUp | boolean | No | Force step-up auth regardless of permission. Default: false |
webhookNotification | boolean | No | Send Slack webhook. Default: false |
projectId | string | No | Project ID (automatically provided) |
Returns: Promise<ApiResponse<IdpAuthResponse[]>>
IdpAuthResponse:
interface IdpAuthResponse {
success: boolean;
sid: string; // Step-up Session ID (on success)
error?: string; // Error message (on failure)
timestamp: number; // Unix timestamp in milliseconds
action: string; // Requested action type
}Example:
const result = await transcodes.openAuthIdpModal({
projectId: '{YOUR_PROJECT_ID}',
resource: 'users',
action: 'delete',
forceStepUp: true,
});
if (result.success && result.payload[0].success) {
const { sid } = result.payload[0];
console.log('Step-up verified, session ID:', sid);
}Server-side verification is required. The sid returned from the client
is not a proof of authority on its own. Send it to your backend and
re-verify it against the Transcodes API before executing any sensitive action.
See Step-up session — verifying sid
server-side
for the full flow
Type Definitions
ApiResponse<T>
interface ApiResponse<T> {
success: boolean;
payload: T;
error?: string;
message?: string;
status?: number;
}AuthResult
interface AuthResult {
token: string;
user: User;
}IdpOpenParams
interface IdpOpenParams {
resource: string;
action: 'create' | 'read' | 'update' | 'delete';
forceStepUp?: boolean;
webhookNotification?: boolean;
}Related
- Token API - Token management
- Member API - Member profile
- Events API - Auth state change events
- Types - Full type definitions