Access Control

Axoniq Insights provides multiple layers of access control to secure the web UI, REST APIs, the AI chat interface, and the PostgreSQL wire protocol endpoint.

Enabling authorization

Authorization is controlled by a single property:

insights.authorization.enabled=true

When enabled (the default), all protected endpoints require authentication. When disabled, all endpoints are accessible without authentication. This is useful for local development but should never be used in production.

Authentication methods

Insights supports several authentication methods that can be used independently or combined.

Local users (username and password)

Insights maintains its own user database backed by SQLite. Passwords are stored using BCrypt encryption.

On first startup, a default admin user is created. The initial password is configured with:

insights.authorization.default-password=admin

Change this password immediately after first login in production environments.

Users can authenticate through:

HTTP Basic Authentication : Include credentials in the request header. Useful for API clients and scripts.
Form login : A login page served at /login for browser-based access.

OAuth2 / OIDC

For single sign-on with an external identity provider, Insights supports OAuth2 and OpenID Connect. See OAuth2 / OIDC Configuration for detailed setup instructions.

When OAuth2 is configured, users authenticate through the external provider (Google, Keycloak, Okta, Azure AD, etc.) and are mapped to Insights users via configurable username mappings.

User management

Users are managed through the Insights UI or the REST API.

REST API

Endpoint Description

Endpoint	Description
`GET /v2/users`	List all users.
`PUT /v2/users`	Create a new user.
`POST /v2/users/{username}`	Update a user’s roles.
`PATCH /v2/users/{username}`	Change a user’s password.
`DELETE /v2/users/{username}`	Delete a user.

GET /v2/users

List all users.

PUT /v2/users

Create a new user.

POST /v2/users/{username}

Update a user’s roles.

PATCH /v2/users/{username}

Change a user’s password.

DELETE /v2/users/{username}

Delete a user.

Roles

Each user has a set of roles. The built-in roles are:

ADMIN : Granted to the default admin user created on startup. Administrators can manage users, contexts, and all configuration.
USER : View data, execute SQL queries, and use the AI chat interface, but cannot manage users or contexts.

PostgreSQL wire protocol authentication

The built-in PostgreSQL wire protocol server (PgWire) has its own authentication layer, independent of the web authentication. This allows SQL clients such as DBeaver, pgAdmin, DataGrip, Grafana, or any PostgreSQL JDBC driver to authenticate.

When a client connects:

The server optionally upgrades the connection to TLS (if insights.jdbc.ssl-enabled=true).
The server requests a cleartext password from the client.
The password is validated against the Insights user database (BCrypt).
On success, the client receives an AuthenticationOk response and can execute queries.

PgWire authentication is controlled by:

insights.jdbc.require-authentication=true

When set to false, connections are accepted without password verification. The database name in the connection URL maps to the Axon Server context name. For example, to query the bikes context:

jdbc:postgresql://localhost:5432/bikes

See JDBC Driver Configuration for the full list of PgWire configuration options including SSL/TLS setup.

Security recommendations

For production deployments:

Enable authorization (insights.authorization.enabled=true).
Change the default admin password before or at first startup.
Configure OAuth2 / OIDC for centralized user management.
Enable SSL/TLS on the PgWire endpoint if it is exposed outside the local network (insights.jdbc.ssl-enabled=true).
Use environment variables for sensitive values like tokens and passwords to keep them out of configuration files.
Require authentication on the PgWire endpoint (insights.jdbc.require-authentication=true, the default).