OAuth Clients

OAuth clients are applications that can authenticate with OctoMesh. Every application that accesses OctoMesh APIs — whether a web application, a background service, or a CLI tool — must be registered as a client.

Accessing OAuth Clients

Navigate to Identity > Clients to access the client management interface.

The list shows all registered clients:

Column	Description
Client ID	Unique identifier for the client
Name	Display name of the client
Enabled	Whether the client is active
URI	The client's base URL

Toolbar Actions

Button	Description
New Client	Register a new client application
Search	Filter clients by ID or name
Export to Excel	Export the client list to an Excel file
Export to PDF	Export the client list to a PDF file
Refresh Data	Reload the client list

Row and Context Actions

Action	Description
Edit	Open the client in the edit form
Delete	Delete the client (context menu, with confirmation)

Creating a Client

Click New Client to open the client creation form.

Basic Information

Field	Required	Description
Client ID	Yes	Unique identifier (cannot be changed after creation)
Client Name	Yes	Display name for the client
Client URI	No	Base URL of the client application
Client Secret	No	Secret for confidential clients (device code, client credentials)

Options

Option	Description
Require Client Secret	Whether the client must authenticate with a secret
Enabled	Whether the client can be used for authentication
Offline Access (Refresh Tokens)	Allow the client to request refresh tokens

Allowed Grant Types

Select which OAuth 2.0 grant types the client can use:

Grant Type	Use Case
authorization_code	Web applications with browser-based login
client_credentials	Service-to-service authentication (no user context)
urn:ietf:params:oauth:grant-type:device_code	Devices and CLI tools without a browser
refresh_token	Refresh expired access tokens

Redirect URIs

Configure where the Identity Service is allowed to redirect after authentication. Click the Add button to add entries.

Each redirect URI must be a full URL (e.g., https://myapp.example.com/callback/).

Post Logout Redirect URIs

Configure where the Identity Service redirects after logout. Click the Add button to add entries.

Allowed CORS Origins

Configure which origins are allowed for cross-origin requests to the Identity Service. Click the Add button to add entries.

note

CORS origins must not have a trailing slash (e.g., https://myapp.example.com).

Allowed Scopes

Configure which API scopes the client can request. Click the Add button to add entries. Common scopes:

Scope	Description
openid	Required for OIDC — provides user identifier
profile	User profile information (name)
email	User email address
role	User roles
octo_api	Full access to all OctoMesh APIs
octo_api.read_only	Read-only access to all OctoMesh APIs

Roles

Select the roles assigned directly to the client in the Roles field. When the client authenticates via the client_credentials flow, these roles — together with any roles inherited from group memberships — are included in its access token, so the client can call role-protected endpoints. It is recommended to assign permissions via groups rather than directly.

Group Memberships

Use the Group Memberships field to add the client to one or more groups. The client inherits all roles assigned to those groups (including nested groups), just like a user.

Click Save to register the client or Cancel to discard.

Editing a Client

Click Edit on a client row to open the edit form. The Client ID is read-only. All other fields can be modified.

Updating the Client Secret

In edit mode, the existing secret is not displayed (it is stored encrypted). To set a new secret:

1. Click Set New Secret
2. Enter the new secret
3. Click Save

Deleting a Client

Right-click a client and select Delete. Confirm the deletion in the dialog.

danger

Deleting a client immediately prevents all applications using that client ID from authenticating. Make sure the client is no longer in use before deleting it.

Default Clients

The following clients are created automatically during system setup:

Client ID	Type	Purpose
octo-cli	Device Code	OctoMesh command-line tool
octo-idenityServices-swagger	Authorization Code (PKCE)	Identity API Swagger UI
octo-data-refinery-studio	Authorization Code (PKCE)	Data Refinery Studio

Overlay URIs and Template-Clean Exports

Default clients such as octo-data-refinery-studio are managed by a blueprint: their Redirect / Post Logout / CORS URIs are re-applied to the environment's canonical values on every tenant lifecycle event. Each URI entry carries a source that decides whether it survives that re-apply:

Source	Added by	Survives blueprint re-apply?
base	The blueprint seed	No — always reset to the blueprint value
api	An operator via this Studio client form or the API	Yes
overlay:<name>	A developer/operator overlay (e.g. local-dev callbacks)	Yes

Overlay URIs let a developer add machine-local callbacks (for example http://localhost:4200/auth-callback after restoring a production backup locally) without destroying the restored production URIs and without those local URIs leaking into a shared export.

Cleaning overlays before a tenant backup

When you export a tenant from Tenant Management (right-click a tenant → Backup), the backup dialog offers a Clean overlay URIs before export checkbox:

• Enabled — every overlay:* URI on every blueprint-managed client is stripped before the dump is created, so the resulting backup is template-clean and safe to re-import as blueprint seed material. base and api URIs are preserved.
• Disabled (default) — the backup captures the tenant exactly as-is, including any overlay URIs.

note

Cleaning is a one-way operation on the live tenant. If you still need the local-dev callbacks afterwards, re-apply them (an operator can re-run the Apply-IdentityOverlay tool, which is idempotent).

For the full source taxonomy, the CLI/MCP equivalents, and the reasoning behind overlays, see the technology guide's Clients and API Scopes — URI Sources and Lifecycle.