Introduction
Authenticating with the Hopsule API is the foundational step for engineering organizations looking to integrate their decision and memory layers into custom workflows and external tooling. By establishing a secure connection between your infrastructure and the Hopsule API, you ensure that every programmatic interaction respects the authority of your team's established governance and preserves the integrity of your organizational judgment. This guide covers the comprehensive lifecycle of credential management, from generating initial API keys in the Hopsule Dashboard to implementing advanced security protocols for large-scale enforcement.
Prerequisites
Before you begin the authentication process, ensure that you meet the following requirements to maintain the security and traceability of your team's context:
An active Hopsule account with a verified email address.
Administrative or Developer role permissions within your organization to access the Developer Settings.
The latest version of the Hopsule CLI installed if you intend to manage tokens via the terminal.
A clear understanding of the decisions and memories you intend to access programmatically.
Understanding Hopsule Authentication Architecture
Hopsule utilizes a multi-layered authentication strategy designed to provide both long-term stability for automated systems and short-term security for interactive sessions. Our philosophy—enforcement is remembrance, not control—extends to our security model. We provide the tools to remember who accessed what context and why, ensuring full traceability across the decision lifecycle.
API Keys (Long-Lived Credentials)
API keys are primarily used for server-to-server communication, CI/CD pipelines, and persistent integrations. These keys act as a permanent bridge to your organization's memory layer. Unlike user sessions, API keys do not expire unless manually revoked or rotated, making them ideal for Hopsule API interactions that require high availability without human intervention.
JWT Tokens (Session-Based Credentials)
For interactive tools like the Hopsule CLI and Hopsule for VS Code, Hopsule employs JSON Web Tokens (JWT). These tokens are short-lived and are typically refreshed automatically through the Hopsule Dashboard or CLI authentication flow. They are tied to a specific user identity, ensuring that every memory appended or decision drafted is attributed to a specific human authority.
Generating API Keys in the Hopsule Dashboard
The Hopsule Dashboard serves as the central command center for managing your organization's programmatic access. Follow these steps to generate your first set of credentials:
Log in to the Hopsule Dashboard and select your organization from the workspace switcher in the top-left corner.
Navigate to the Settings menu by clicking the gear icon located at the bottom of the primary sidebar.
Within the Settings view, click on the Developer tab. This section contains all configurations related to the Hopsule API, Hopsule MCP, and third-party integrations.
Locate the API Keys section and click the Generate New Key button.
In the modal that appears, provide a Key Name that describes its intended purpose (e.g., "Production CI/CD Pipeline" or "Internal Governance Bot").
Select the Access Scope. You can choose between "Read-Only" (access to view decisions and memories) or "Read/Write" (ability to draft decisions and append memories). Note that even with Read/Write access, the Hopsule API enforces that memories are append-only and can never be deleted.
Click Create Key. The Hopsule Dashboard will display your API key once. Important: Copy this key immediately and store it in a secure credential manager. For security reasons, Hopsule does not store the raw key and cannot display it again.
Click Done to return to the Developer dashboard.
Authenticating via the Hopsule CLI
The Hopsule CLI provides an interactive TUI (Terminal User Interface) for developers to manage their connection to the Hopsule memory system without leaving their development environment. This is particularly useful for setting up local enforcement of decisions.
Open your terminal and type
hopsule auth login.The CLI will provide a unique device code and attempt to open your default web browser to the Hopsule Dashboard authentication page.
Confirm the device code in the browser and authorize the Hopsule CLI to access your account.
Once authorized, the CLI will receive a secure token. You can verify your status by running
hopsule status, which will display your current organization, active Context Packs, and connection health using our signature ASCII art interface.If you are working in a headless environment, you can manually set your API key by using the command
hopsule auth set-key [YOUR_API_KEY].
Implementing Authentication in Code
When making direct requests to the Hopsule API, you must include your credentials in the HTTP headers. Hopsule requires all traffic to be encrypted via TLS 1.3, ensuring that your organizational context remains confidential during transit.
To authenticate a request, use the Authorization header with the Bearer scheme:
All API requests are rate-limited based on your plan tier (Free, Pro, or Enterprise). If you exceed these limits, the Hopsule API will return a 429 status code. This ensures that the preservation of context remains performant for all members of the organization.
Security Standards and Data Sovereignty
At Hopsule, security is a baseline guarantee, not a premium feature. Whether you are using our cloud-hosted Hopsule Dashboard or the Hopsule Enterprise (Self-Hosted) version, the following protections are always active:
End-to-End Encryption (E2EE): All memories and decisions are encrypted before they are persisted, ensuring that only authorized members of your organization can decrypt and read the reasoning behind your decisions.
Data at Rest: All data is stored using AES-256 encryption. This applies to every entry in your Knowledge Graph and every Capsule in your Context Packs.
Data in Transit: We enforce TLS 1.3 for all API and dashboard communications to prevent intercept attacks.
Audit Trails: Every authentication event and API call is logged in the Activity Feed within the Hopsule Dashboard. This allows engineering leaders to see exactly how and when organizational judgment was accessed or modified.
Managing Context Packs and Capsules via API
Authentication also governs how you interact with Context Packs (Capsules). Capsules are portable bundles of decisions and memories designed to survive time and system changes. When authenticating via the Hopsule API, you must ensure your token has the appropriate permissions to access specific Capsules.
Draft Capsules: Accessible only by the creator or organization admins.
Active Capsules: Accessible by any authenticated member with the correct scope.
Frozen/Historical Capsules: Read-only access to ensure the preservation of past reasoning.
By using the X-Hopsule-Capsule-ID header in your API calls, you can scope your authentication to a specific set of decisions, which is highly recommended for AI agents using the Hopsule MCP.
Best Practices for API Security
To maintain the highest level of governance and prevent the loss of organizational memory, follow these best practices:
Principle of Least Privilege: Only grant "Read/Write" scopes to services that absolutely require the ability to draft decisions or append memories. Use "Read-Only" for AI agents and visualization tools.
Environment Variables: Never hardcode API keys in your source code. Use secure environment variable management systems, especially when integrating with the Hopsule IDE Extension or Hopsule CLI.
Regular Rotation: Rotate your API keys every 90 days. You can do this in the Hopsule Dashboard by generating a new key, updating your services, and then deprecating the old key.
Monitor the Activity Feed: Regularly check the Hopsule Dashboard's activity feed for any unusual authentication patterns. Hopsule remembers every access attempt, providing you with the data needed for security audits.
Use Hopsule MCP for AI Agents: Instead of giving raw API keys to AI agents, use the Hopsule MCP. This provides a read-only, context-aware bridge that ensures AI agents can understand your decisions without having the authority to mutate them.
Troubleshooting Authentication Issues
If you encounter difficulties connecting to the Hopsule API, refer to the following table to identify and resolve common issues.
Issue | Possible Cause | Solution |
|---|---|---|
401 Unauthorized | The API key is missing, invalid, or has been revoked in the Hopsule Dashboard. | Verify the |
403 Forbidden | The authenticated user or key does not have the required scope for the requested action. | Check the scope of the API key. Ensure you aren't trying to "Accept" a decision with a "Read-Only" key. |
429 Too Many Requests | The organization has exceeded the rate limits associated with their current plan tier. | Implement exponential backoff in your integration or upgrade to a higher Hopsule plan for increased limits. |
Token Expired | The short-lived JWT used by the Hopsule CLI or IDE extension has reached its end of life. | Run |
Connection Refused | A firewall or proxy is blocking outgoing traffic to | Ensure your network allows traffic to Hopsule and that your environment supports modern TLS standards. |
Frequently Asked Questions
Can I use the same API key for multiple projects?
While possible, it is not recommended. To maintain the integrity of your Knowledge Graph and ensure clear traceability, you should generate unique API keys for each major project or service. This allows you to revoke access for one project without affecting others and provides better visibility in the Hopsule Dashboard activity feed.
How does authentication work for Hopsule Enterprise (Self-Hosted)?
In a self-hosted environment, you maintain full data sovereignty. Authentication still follows the API key and JWT model, but the credentials never leave your infrastructure. Your internal security team manages the issuance and rotation of these keys, and Hopsule provides the audit trails and compliance reporting tools to monitor them.
Does Hopper have its own API key?
Hopper, our built-in AI assistant, operates within your existing authentication context. When you interact with Hopper in the Hopsule Dashboard or via the Hopsule for VS Code extension, it uses your user permissions to suggest improvements or explain existing decisions. Hopper is advisory only and does not possess its own independent authority to bypass your organization's governance rules.
Related Articles
Managing Decision Lifecycles via the Hopsule API
Integrating Hopsule CLI with CI/CD Pipelines
Configuring Webhooks for Real-time Decision Notifications
Understanding Scopes and Permissions in Hopsule
SHARE ON SOCIAL MEDIA
