SignStack's API needs to securely authenticate two fundamentally different types of actors:

1. Human Users: People interacting with the SignStack web application (like Blueprint designers or administrators).

2. Machine Clients: Your backend server or other automated systems integrating with the SignStack API.

These two actors have different authentication needs and security contexts, so SignStack uses two distinct authentication mechanisms. Understanding this difference is key to secure integration.

1. User-Level Authentication (Via Identity Provider) 🧑‍💻

This method authenticates a specific human user and proves their personal identity.

• Mechanism: SignStack integrates with a third-party Identity Provider (IdP) like Firebase Authentication (or Auth0, etc.).

• Token: When a user logs into the SignStack web application, the IdP issues a short-lived ID Token (e.g., a Firebase ID Token).

• Usage: This token is primarily used for:

  • Authenticating API calls made from the SignStack web UI to the SignStack backend.

  • Accessing special user-centric API endpoints (like GET /v1/me/organizations) which operate across all organizations a user belongs to.

• Proof: Verifying this token proves who the user is based on their login credentials.

2. Organization-Level Authentication (Via SignStack API Key/JWT)

This method authenticates a machine client acting on behalf of a specific SignStack Organization.

• Mechanism: The two-part system using a long-lived SignStack API Key exchanged for a short-lived SignStack JWT Access Token.

• Token: The SignStack JWT Access Token contains the organizationId and the specific permissions (scopes) granted to the API Key.

• Usage: This token is used for all standard, organization-scoped API calls made from your backend server (e.g., POST /workflows/from-blueprint, GET /templates).

• Proof: Verifying this token proves that the request is authorized to act on behalf of a specific organization with a specific set of permissions.

Why Two Systems?

This separation provides several benefits:

• Appropriate Security: Human user authentication leverages robust IdP features (like MFA, social logins). API authentication uses scoped keys and short-lived tokens suitable for server-to-server communication.

• Clear Context: The token type immediately tells the backend whether the request is from a human user (potentially acting across orgs) or a machine client acting within a single org context.

• Flexibility: It correctly handles the "consultant" use case where a single human user needs access to multiple distinct organizations. Their user identity (Firebase token) grants access to the list of orgs, while their API key (SignStack JWT) grants access within a specific org.

Summary

Actor	Authentication Method	Token Used in Header	Primary Use Case	Scope
Human User	Identity Provider (e.g., Firebase)	Firebase ID Token	SignStack Web UI, /me API endpoints	User-centric
API Client	SignStack API Key -> SignStack JWT	SignStack Access Token	Standard Org-scoped API calls	Organization-centric

Understanding which token to use in which context is essential for building secure and correct integrations with SignStack.

➡️ Next: Beyond the Basics: Securely Embedding Components (Session Tokens)