SignStack uses a robust, modern authentication system for its API, designed to be both secure and developer-friendly. This guide explains the two core components: long-lived API Keys and short-lived JWT Access Tokens.

Understanding this system is crucial for securely integrating your application with the SignStack API.

The Two-Part System: Keys vs. Tokens 🔑

Instead of using one static key for all requests (which is a security risk), SignStack uses a more secure two-part system, similar to platforms like Stripe:

1. API Key (Long-Lived Secret):

   • What it is: A unique, secret credential you generate in your SignStack organization settings (e.g., sk_live_publicKey_secret). It includes scoped permissions (Roles).

   • Its Job: It acts like your master key or password. Its only purpose is to securely authenticate with SignStack's /auth/token endpoint to obtain a temporary Access Token. It should never be sent with regular API calls.

   • Security: Keep your API Keys absolutely secret and secure on your backend server. Never expose them in frontend code.

2. JWT Access Token (Short-Lived Credential):

   • What it is: A standard JSON Web Token (JWT) that SignStack issues after you successfully authenticate with your API Key.

   • Its Job: It acts like a temporary session token or keycard. This is the token you include in the Authorization: Bearer <token> header for all standard API calls (like creating workflows or fetching blueprints).

   • Security: Access Tokens expire automatically (typically after 1 hour). If one is accidentally leaked, the security risk is significantly reduced because its validity window is very short.

Understanding Your API Key Structure

Your SignStack API Key follows a standard, secure format:

[prefix]_[publicKey]_[secret]

• prefix: Identifies the key type (e.g., sk_live_ for Secret Key, Live environment; sk_test_ for Secret Key, Test environment).

• publicKey: A unique, non-secret identifier (like a username) used by SignStack to quickly look up your key's record. It's safe to log this part for debugging.

• secret: A long, cryptographically random, highly confidential string (like a password). This part must never be logged or exposed. SignStack hashes this part securely for verification.

The Authentication Flow

Here’s the standard process for authenticating API calls:

1. Generate API Key: Create an API Key in your SignStack dashboard (Organization Settings -> Developer -> API Keys). Assign appropriate Roles (permissions) and securely copy the generated key string. Store this key securely in your backend's configuration or secret management system.

2. Exchange Key for Token: Before making regular API calls (or whenever your previous token expires), your backend server makes a request to SignStack's token endpoint:

   • Endpoint: POST /v1/auth/token

   • Request Body:

     {
       "apiKey": "sk_live_..." // Your full, secret API Key
     }

     json

   • SignStack Logic: SignStack securely validates your API Key.

   • Response (200 OK): If valid, SignStack returns a short-lived JWT Access Token.

     {
       "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // The JWT
       "expiresIn": 3600 // Validity period in seconds (e.g., 1 hour)
     }

     json

3. Make API Calls with JWT: Use the obtained accessToken in the Authorization header for all other SignStack API calls.

   curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
     "[https://api.signstack.com/v1/organizations/me/blueprints](https://api.signstack.com/v1/organizations/me/blueprints)"

   bash

4. Handle Expiration: When an API call returns a 401 Unauthorized error, it likely means your accessToken has expired. Repeat Step 2 to get a fresh token and retry the original API call.

Security Benefits

This two-part system is the industry standard for secure APIs because:

• Reduced Attack Window: Short-lived tokens significantly limit the time an attacker has if a credential is leaked.

• Protection of Master Secret: The highly sensitive API Key is transmitted very rarely, minimizing its exposure.

• Scoped Permissions: API Keys (and therefore the JWTs derived from them) can be granted limited permissions via Roles, enforcing the principle of least privilege.

Always handle your API Keys with the utmost security. Use the short-lived Access Tokens for all routine API interactions.

➡️ Next: Beyond the Basics: User-Level vs. Org-Level Authentication