LYNIO.
← Back to all documentation
IdentityBy Lynio-Support

Registering Applications and API Keys

Application and Integration Overview

Lynio IAM supports OIDC/OAuth2 client application registration and custom API key generation to facilitate secure authentication and API integration. This guide covers how to register client applications, manage confidential and public clients, and implement HMAC request signing for secure API key calls.

Registering OIDC Applications

OIDC application registration represents OAuth2 clients authorized to authenticate users against Lynio IAM. Applications are managed under the Applications tab within the Identity & Access Management page (/identity) in the LYNIO Console or via the HTTP API.

Application Properties

When registering an application, you must define:

  • Name: A friendly identifier for the application.
  • Type: The client classification (determines secret handling).
  • Redirect URIs: A list of authorized callback URLs where users are returned after successful authentication. In the Console, this is input as a newline-separated list.
  • Scopes: Requested user data permissions (defaults to openid, profile, and email).

Public vs. Confidential Clients

Lynio IAM treats client types with strict security rules:

  • Public (SPA/Mobile): For applications running in browser environments (e.g. React SPAs) or mobile devices where credentials cannot be stored securely. These clients do not have client secrets.
  • Confidential (Server-side): For backend applications running on private servers. These clients are issued client secrets.

Note that while the database schema and API support a third client type, "Service" (intended for machine-to-machine client credentials grant), this option is not directly selectable in the Console UI (which only offers Public (SPA/Mobile) and Confidential (Server-side)). Instead, "Service" client registrations are managed via the HTTP API.

Client Secret Lifecycle & Storage

Lynio IAM enforces a strict one-time disclosure policy for Client Secrets:

  1. Client ID Generation: Auto-generated with a prefix of app_ followed by a 16-byte random, URL-safe base64 string.
  2. Client Secret Generation: Auto-generated for confidential and service types, starting with aps_ followed by a 32-byte random, URL-safe base64 string.
  3. Database Storage: The raw client secret is never stored. The system immediately hashes it using bcrypt and writes only the hash to the database.
  4. One-Time Handover: Since only the hash exists in the database, the raw client secret is returned exactly once in the JSON response of the creation API call (POST /api/v1/applications), accompanied by the warning: "Save this secret now - it will not be shown again!".
  5. Console UI Notification: When creating a client via the Console, the UI captures the creation response and displays a dedicated, centered modal. This modal displays the raw Client Secret in a read-only field, prompting the administrator to copy and save it securely before closing.

HTTP API Application Endpoints

You can manage applications programmatically using the following endpoints:

  • List Applications: GET /api/v1/applications (client secret fields are omitted)
  • Create Application: POST /api/v1/applications (returns client ID and the raw secret once for confidential/service clients)
  • Update Application: PUT /api/v1/applications/:id (allows modifying the name and redirect URIs)
  • Delete Application: DELETE /api/v1/applications/:id

API Keys and HMAC Request Signing

For machine-to-machine integrations and programmatic script access, Lynio IAM supports API keys that use secure HMAC request signing.

API Key Properties

API keys contain:

  • key_id: Starts with the prefix lk_ (stored in plain text in database).
  • key_secret: Starts with the prefix lks_ (stored hashed with bcrypt in database and returned only once upon key creation).

HMAC Signing Verification

Lynio IAM validates API key requests using an HMAC signature rather than passing raw keys over the wire.

Authorization Header Format

API calls using keys must specify the signature in the Authorization header:

Authorization: HMAC-SHA256 KeyID=lk_xxx, Timestamp=1234567890, Signature=xxx

Replay Window Protection

To prevent replay attacks, the server verifies that the timestamp in the Authorization header matches the server's time:

  • Requests are rejected if the timestamp is more than 300 seconds (5 minutes) in the past.
  • Requests are rejected if the timestamp is more than 60 seconds in the future.

Canonical Request Construction

The signature is calculated over a canonical representation of the request, preventing tampering with the path, method, time, or request payload. The canonical format is constructed as:

Method + "\n" + Path + "\n" + Timestamp + "\n" + Base64(SHA256(Body))

Signature Verification

The client computes the signature by hashing the canonical request string with the raw key secret (lks_...) using the HMAC-SHA256 algorithm. The server computes the same signature using its stored bcrypt key secret, and verifies the client signature using a constant-time comparison (hmac.Equal) to prevent timing side-channel attacks.