Authentication

Overview

Kinotic supports multiple authentication methods to secure your applications. Every connection to a Kinotic server requires authentication — the platform identifies the caller and establishes a session before any service calls are allowed.

Authentication Methods

• Email and Password — Built-in user management with secure credential storage. Ideal for getting started quickly or for applications that manage their own user base.
• OIDC Providers — Connect any standard OpenID Connect provider including Google, Microsoft, Okta, and others. Your organization admin enables OIDC configurations for your application — including platform-provided social providers pre-registered with Kinotic OS.

This page covers what an application developer needs to know. For the platform-level model behind these mechanisms — scope isolation, the OidcConfiguration entity, signup and login flows — see System Security and Organization Management.

Scoped Authentication

Every authentication request includes a scope that identifies which layer the caller is authenticating against. For application developers, this is always the APPLICATION scope with your application's ID.

These headers are required on every connection. They ensure that users are authenticated against the correct user pool — a user in Application A cannot access Application B, even if both applications use the same OIDC provider.

Connecting with Email and Password

Use the connectHeaders option to provide credentials when connecting to a Kinotic server:

import { Kinotic } from '@kinotic-ai/core'

await Kinotic.connect({
    host: 'localhost',
    port: 58503,
    connectHeaders: {
        login: 'user@example.com',
        passcode: 'password',
        authScopeType: 'APPLICATION',
        authScopeId: 'my-application'
    }
})

The platform looks up the user by email within your application's scope, verifies the password against a securely stored bcrypt hash, and establishes a session.

Connecting with OIDC

For token-based authentication with an OIDC provider (Google, Microsoft, etc.), pass a Bearer token in the Authorization header. Use an async function to support automatic token refresh:

import { Kinotic } from '@kinotic-ai/core'

await Kinotic.connect({
    host: 'localhost',
    port: 58503,
    connectHeaders: async () => ({
        Authorization: `Bearer ${await getOidcToken()}`,
        authScopeType: 'APPLICATION',
        authScopeId: 'my-application'
    })
})

The platform validates the JWT against the OIDC configurations enabled for your application, matches the token's email to a pre-existing user in your application's scope, and establishes a session.

How OIDC Works with Your Application

1. Your platform administrator enables one or more OIDC configurations for your application (e.g., Google, Microsoft)
2. Your frontend initiates the OAuth flow with the provider — the user sees the provider's consent screen
3. The provider returns a JWT to your frontend
4. Your frontend connects to Kinotic with the JWT and your application's scope headers
5. The platform validates the token, looks up the user, and creates a session

Reusable Providers

Kinotic OS registers once with providers like Google and Microsoft. The platform operator provisions these as OidcConfiguration entities; your organization admin enables them for your application by adding the configuration id to your application's oidcConfigurationIds. End users see "Kinotic OS" on the consent screen, and your application benefits without any provider registration.

The same OidcConfiguration shape is used for an organization's enterprise SSO (e.g. a corporate Okta instance) — see System Security for how the platform-vs-org distinction is captured by reference rather than by a flag on the entity.

User Management

Application-scope users are pre-created by an administrator before they can authenticate. This is a deliberate security design — having a valid Google account does not automatically grant access to your application. Self-service signup applies to the Organization scope (the admin who runs the org); the same data model supports application-scope self-signup, but enabling it is admin-controlled.

Your organization or platform administrator manages users through the IamUserService:

• Local users are created with an email and password
• OIDC users are created with an email only — the OIDC subject is linked automatically on first login

For details on user and OIDC configuration management, see the Organization Management platform guide.

Policy-Based Authorization

Once authenticated, authorization is handled by the platform. Policies are applied declaratively using decorators on your services and entities — no authorization logic in your application code.

The authenticated user's identity (email, roles, metadata) is available in ABAC policy expressions through the participant attribute path.

See Access Control for details on writing ABAC policies.