Kroki Authentication: Methods & Security Best Practices (2026)

Authentication overview

Kroki serves as an open-source tool for rendering diagrams from text-based definitions. Its authentication model varies significantly depending on whether users interact with the public Kroki instance or a self-hosted server. The public Kroki service is designed for broad, non-commercial use and generally does not require explicit authentication for basic diagram generation requests. This allows developers to quickly integrate diagramming capabilities into their applications or documentation without needing to manage API keys or tokens.

However, when deploying a self-hosted Kroki server, administrators gain the flexibility to implement and enforce various authentication and authorization mechanisms. This capability is crucial for scenarios requiring controlled access, resource management, or compliance with organizational security policies. Self-hosting enables organizations to secure their diagram generation endpoints, ensuring that only authorized users or systems can access the service and generate diagrams, especially when dealing with sensitive information or proprietary diagram definitions.

The choice of authentication method for a self-hosted Kroki instance typically depends on the existing infrastructure, security requirements, and integration needs. Common approaches include API keys for simple client-server authentication, or more robust token-based systems like OAuth 2.0 or JSON Web Tokens (JWTs) for applications requiring delegated authorization and stateless authentication. Understanding the distinction between the public and self-hosted deployments is fundamental to establishing an appropriate authentication strategy for Kroki.

Supported authentication methods

While the public Kroki instance often operates without explicit client-side authentication, self-hosted Kroki deployments offer administrators several options for securing access. The specific authentication methods available depend on how the Kroki server is configured and potentially integrated with an API gateway or reverse proxy.

Here's a breakdown of common authentication methods applicable to self-hosted Kroki instances:

For API Key authentication, clients typically include the key in a custom HTTP header (e.g., X-API-Key) or as a query parameter. Token-based authentication, such as using JSON Web Tokens (JWTs), commonly involves sending the token in the Authorization header with the Bearer scheme. OAuth 2.0, as defined by oauth.net, provides a framework for delegated authorization, allowing third-party applications to obtain limited access to an HTTP service on behalf of a resource owner.

Administrators of self-hosted Kroki servers can integrate these methods by configuring their reverse proxy (e.g., Nginx, Apache) or API Gateway (e.g., Kong Gateway, AWS API Gateway) to enforce authentication before requests reach the Kroki application. This externalizes the authentication logic, keeping the Kroki application itself focused on diagram rendering.

Getting your credentials

The process of obtaining credentials for Kroki largely depends on whether you are using the public instance or a self-hosted server.

Public Kroki Instance

For the public, non-commercial Kroki instance, explicit credentials are generally not required for basic diagram generation. You can typically send requests directly to the public endpoint without needing an API key or token. This design choice prioritizes ease of use and accessibility for quick prototyping and open-source projects. However, users should be aware that requests to the public instance are subject to its usage policies and any rate limiting that may be in place. No account registration or credential generation process is needed for this use case.

Self-Hosted Kroki Server

When you deploy your own Kroki server, you are responsible for establishing and managing your authentication credentials. The Kroki application itself does not inherently provide a user management or API key generation system out-of-the-box. Instead, authentication is typically implemented at the infrastructure layer surrounding the Kroki server.

Common approaches for credential management in a self-hosted environment include:

• API Key Generation: If you're using an API Gateway (e.g., Kong Gateway, cloud-provider specific gateways like AWS API Gateway), you can use its features to generate API keys. These keys are then configured within the gateway to control access to your Kroki endpoint. The gateway validates the incoming API key against its stored keys before forwarding the request to Kroki.
• Token Issuance (JWT/OAuth 2.0): For token-based authentication, you would typically integrate an Identity Provider (IdP) or an Authorization Server (AS) with your application ecosystem. This server is responsible for issuing access tokens (e.g., JWTs) after a user or client successfully authenticates. Your client application would then obtain a token from the IdP/AS and include it in requests to Kroki. The API Gateway or a custom middleware would then validate these tokens.
• Reverse Proxy Configuration: For simpler setups, you can configure your reverse proxy (e.g., Nginx) to enforce HTTP Basic Authentication or to check for specific headers/tokens before proxying requests to Kroki. This involves defining usernames/passwords or acceptable tokens directly within the proxy's configuration files.

The specific steps for obtaining or generating credentials will depend on your chosen authentication method and the tools you use to implement it. Always refer to the documentation of your API Gateway, Identity Provider, or reverse proxy for detailed instructions on credential creation and management.

Authenticated request example

Given that the public Kroki instance generally does not require authentication, an authenticated request example primarily applies to self-hosted Kroki servers where an authentication layer has been implemented. Let's assume a self-hosted Kroki server is protected by an API key, expected in an X-API-Key header.

This example demonstrates how to send a request to a self-hosted Kroki server with an API key using curl. The request will generate a simple PlantUML diagram.

curl -X POST \
  'https://your-kroki-instance.com/plantuml/svg' \
  -H 'X-API-Key: YOUR_SECURE_API_KEY_HERE' \
  -H 'Content-Type: text/plain' \
  --data-binary '@-' << EOF
@startuml
Alice -> Bob: Authentication request
Bob --> Alice: Authentication response
@enduml
EOF

In this example:

• https://your-kroki-instance.com/plantuml/svg: This is the endpoint of your self-hosted Kroki server, specifically for PlantUML diagrams rendered as SVG. You would replace your-kroki-instance.com with the actual domain of your server.
• -H 'X-API-Key: YOUR_SECURE_API_KEY_HERE': This header carries your API key. You must replace YOUR_SECURE_API_KEY_HERE with the actual API key generated for your self-hosted instance. The API Gateway or reverse proxy protecting Kroki would validate this key.
• -H 'Content-Type: text/plain': Specifies that the body of the request is plain text, which is the format Kroki expects for diagram definitions.
• --data-binary '@-' << EOF ... EOF: This sends the PlantUML diagram definition as the request body.

If you were using a token-based authentication method like JWT, the header would typically look like this:

curl -X POST \
  'https://your-kroki-instance.com/plantuml/svg' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN_HERE' \
  -H 'Content-Type: text/plain' \
  --data-binary '@-' << EOF
@startuml
Alice -> Bob: Authentication request
Bob --> Alice: Authentication response
@enduml
EOF

In this JWT example, YOUR_JWT_TOKEN_HERE would be the access token obtained from your Identity Provider. The API Gateway or middleware would then validate the JWT's signature and claims before allowing access to Kroki.

Security best practices

Securing your Kroki deployments, especially self-hosted instances, requires adherence to general API security best practices. While Kroki itself focuses on rendering, the surrounding infrastructure is key to its security posture.

1. Use HTTPS Everywhere: Always enforce HTTPS for all communication with your Kroki server. This encrypts data in transit, protecting sensitive diagram definitions and authentication credentials from eavesdropping. This is a fundamental principle for secure web communication.
2. Secure API Key Management: If using API keys, treat them like passwords.
• Never hardcode API keys directly into client-side code or commit them to version control.
• Store API keys securely using environment variables, dedicated secret management services (e.g., AWS Secrets Manager, HashiCorp Vault), or configuration files with restricted access.
• Rotate API keys regularly to mitigate the risk of compromised keys.
• Implement rate limiting on your API Gateway to prevent brute-force attacks on API keys.
3. Token Validation and Management (for JWT/OAuth 2.0):
• Validate all incoming tokens: Ensure tokens are signed by a trusted issuer, have not expired, and contain the expected claims.
• Use short-lived access tokens: Minimize the window of opportunity for token misuse if compromised. Implement refresh tokens for obtaining new access tokens.
• Securely store refresh tokens: Refresh tokens should be stored with the highest level of security, as their compromise can lead to persistent access.
4. Least Privilege Principle: Configure your authentication system to grant only the minimum necessary permissions. For Kroki, this might mean ensuring that API keys or tokens only allow access to diagram generation endpoints and not to server configuration or other sensitive resources if they were exposed.
5. Network Segmentation and Firewalls: Deploy your self-hosted Kroki server behind a firewall and within a segmented network. Restrict inbound traffic to only the necessary ports and source IPs. This adds a layer of defense against unauthorized access.
6. Regular Security Audits and Logging: Implement comprehensive logging for all API requests, especially authentication attempts. Regularly review these logs for suspicious activity. Conduct security audits of your Kroki server and its surrounding infrastructure to identify and address vulnerabilities.
7. Keep Kroki and Dependencies Updated: Regularly update your Kroki server instance and all its underlying dependencies (operating system, runtime, diagramming tools) to the latest versions to patch known security vulnerabilities.
8. Protect Against Malicious Input: While Kroki is designed to render text, ensure that input validation is in place at your API Gateway or application layer to prevent potential injection attacks or excessive resource consumption from malformed diagram definitions.

By implementing these practices, organizations can significantly enhance the security posture of their self-hosted Kroki deployments, protecting both the service and the data it processes.