SignStack provides embeddable web components (like <signstack-signing-ceremony>) allowing you to create a seamless, white-label experience within your own application. However, authenticating these components requires a special approach to avoid exposing your secret API keys in the end-user's browser.

The solution is short-lived, single-purpose Session Tokens.

The Security Challenge: Never Expose Secret Keys

Your main SignStack API Key (sk_live_... or sk_test_...) is highly sensitive and must never be included in frontend JavaScript code or sent directly from a user's browser. Doing so would allow anyone inspecting the code to steal your key and gain full access to your SignStack organization.

The Solution: Backend-Generated Session Tokens

The secure pattern involves your backend server acting as a trusted intermediary to obtain a temporary, limited-scope token for the frontend component.

1. User Action: An end-user in your application needs to interact with an embedded SignStack component (e.g., view a document to sign).

2. Your Backend Requests a Token: Your backend server makes a secure, server-to-server API call to a dedicated SignStack endpoint. It authenticates using its secret API Key. This request specifies the context for the session (e.g., the workflowId and participantId the user needs to act as).

   • Endpoint: POST /v1/auth/session-tokens

   • Request Body:

     {
       "workflowId": "wf_123...",
       "participantId": "p_jane_doe_...",
       "expiresInMinutes": 15 // Request a short lifetime
     }

     json

3. SignStack Issues Session Token: SignStack validates the API Key and generates a special, short-lived Session Token. This token is narrowly scoped: it only grants permission for the specified participant to perform actions within the specified workflow for a limited time (e.g., 15 minutes).

4. Backend Sends Token to Frontend: Your backend server securely passes this temporary Session Token to your frontend application (e.g., as part of the initial page load data or via a dedicated secure API call from your frontend to your backend).

5. Component Uses Session Token: Your frontend code initializes the SignStack web component, passing the sessionToken as a property or attribute.

   <signstack-signing-ceremony session-token="<TEMPORARY_SESSION_TOKEN>">
   </signstack-signing-ceremony>

   plaintext

6. Component Authenticates: The SignStack web component now uses this short-lived sessionToken in the Authorization: Bearer <token> header for all its direct calls to the SignStack API (e.g., to fetch document details or submit field values).

Benefits

• Maximum Security: Your secret API Key never leaves your trusted backend server.

• Limited Scope: Session Tokens are tied to a specific user and workflow, minimizing risk if compromised.

• Short Lifespan: Tokens expire quickly (e.g., 5-15 minutes), further reducing the attack window.

• Customer Control: Your backend remains the gatekeeper, controlling who gets a session token and when.

This backend-mediated Session Token flow is the standard, secure method for authenticating embedded UI components that need to interact directly with a third-party API.

➡️ Next: Beyond the Basics: Managing Your Organization via API (RBAC)