Clients and API Scopes

In OAuth 2.0, a client is any application that requests access on behalf of a user or itself. API scopes define what operations a client is allowed to perform. The Identity Service manages both per tenant.

Client Types

OctoMesh supports three client types, each designed for a different use case:

Authorization Code Client

For web applications where a user interacts through a browser. Uses the Authorization Code flow with PKCE.

octo-cli -c AddAuthorizationCodeClient \
  -id "my-web-app" \
  -n "My Web Application" \
  -u "https://myapp.example.com/" \
  -ru "https://myapp.example.com/callback"

Characteristics:

• User authenticates via browser redirect
• PKCE required (no client secret needed for public SPAs)
• Supports refresh tokens with offline_access scope
• User claims included in tokens

Default example: octo-data-refinery-studio — the Data Refinery Studio web application.

Client Credentials Client

For service-to-service communication without user interaction. The service authenticates with its own client ID and secret.

octo-cli -c AddClientCredentialsClient \
  -id "my-background-service" \
  -n "Background Processor" \
  -s "MyServiceSecret123"

Characteristics:

• No user context — tokens have no sub claim
• Authenticates with client ID + client secret
• Bypasses tenant authorization middleware (no allowed_tenants check)
• Used for background jobs, data pipelines, automated processes

Device Code Client

For devices and CLI tools that cannot open a browser directly. The user authenticates on a separate device.

octo-cli -c AddDeviceCodeClient \
  -id "my-iot-device" \
  -n "IoT Sensor Gateway" \
  -s "DeviceSecret123"

Characteristics:

• Device displays a URL and code for the user to enter
• User authenticates on any browser-capable device
• Device polls for completion
• Supports offline_access for long-lived refresh tokens

Default example: octo-cli — the OctoMesh command-line tool.

Default Clients

When the Identity Service is set up, these clients are created automatically:

Client ID	Type	Purpose
octo-cli	Device Code	CLI tool for administration
octo-idenityServices-swagger	Authorization Code (PKCE)	Swagger UI for Identity API
octo-data-refinery-studio	Authorization Code (PKCE)	Data Refinery Studio (auto-provisioned; RefineryStudioUrl defaults to https://localhost:4200)

Managing Clients

List, Update, Delete

# List all clients
octo-cli -c GetClients

# Update a client
octo-cli -c UpdateClient -id "my-web-app" -n "Updated Name" -u "https://new-url.com/"

# Delete a client
octo-cli -c DeleteClient -id "my-web-app"

Client Secrets

Client credentials and device code clients require secrets. Secrets are stored as SHA256 hashes.

# Create a new secret with expiration
octo-cli -c CreateApiSecretClient -cid "my-service" -e "2027-12-31" -d "Production secret"

# List secrets
octo-cli -c GetApiSecretsClient -cid "my-service"

# Delete a secret
octo-cli -c DeleteApiSecretClient -cid "my-service" -s "<sha256-value>"

API Scopes

API scopes control which operations a client can perform. A client must be granted a scope to include it in token requests.

Default API Scopes

OctoMesh uses a unified set of API scopes shared across all services:

Scope	Access Level	Description
octo_api	Full access	Read and write access to all OctoMesh APIs
octo_api.read_only	Read only	Read-only access to all OctoMesh APIs

Managing API Scopes

# List all scopes
octo-cli -c GetApiScopes

# Create a custom scope
octo-cli -c CreateApiScope -n "myAPI.admin" -dn "Admin Access" -d "Full administrative access" -e true

# Update a scope
octo-cli -c UpdateApiScope -n "myAPI.admin" -dn "Updated Name"

# Delete a scope
octo-cli -c DeleteApiScope -n "myAPI.admin"

Granting Scopes to Clients

Use AddScopeToClient to grant a client access to specific API scopes:

# Grant asset repository access
octo-cli -c AddScopeToClient -id "my-web-app" -n "octo_api"

# Grant read-only API access
octo-cli -c AddScopeToClient -id "my-web-app" -n "octo_api.read_only"

A client can only request scopes it has been granted. If a client requests a scope it does not have, the token will not include that scope.

API Resources

API resources group related scopes and can have their own secrets (for API introspection).

Default API Resources

Resource	Display Name	Description	Scopes
octoAPI	Octo API	Unified access to all Octo platform APIs	octo_api, octo_api.read_only

Managing API Resources

# List all resources
octo-cli -c GetApiResources

# Create a resource with scopes
octo-cli -c CreateApiResource -n "myAPI" -dn "My Custom API" -d "Custom API" -s "myAPI.read,myAPI.write"

# Update a resource
octo-cli -c UpdateApiResource -n "myAPI" -dn "Updated API Name"

# Delete a resource
octo-cli -c DeleteApiResource -n "myAPI"

API Resource Secrets

API resources can have secrets for token introspection:

# Create a secret
octo-cli -c CreateApiSecretApiResource -n "myAPI" -e "2027-12-31" -d "Introspection secret"

# List secrets
octo-cli -c GetApiSecretsApiResource -n "myAPI"

# Delete a secret
octo-cli -c DeleteApiSecretApiResource -n "myAPI" -s "<sha256-value>"

Identity Resources

Identity resources define which user claims are included in identity tokens. OctoMesh configures these by default:

Resource	Claims	Purpose
openid	sub	Required for OIDC — user identifier
profile	name, given_name, family_name	User profile information
email	email, email_verified	User email address
role	role	User roles (custom resource)

When a client requests scope=openid profile email role, the resulting token includes all claims from these identity resources plus the OctoMesh-specific claims (tenant_id, allowed_tenants).

Example: Registering a New Web Application

Complete workflow for adding a new web application to OctoMesh:

# 1. Create the client
octo-cli -c AddAuthorizationCodeClient \
  -id "my-dashboard" \
  -n "My Dashboard App" \
  -u "https://dashboard.example.com/" \
  -ru "https://dashboard.example.com/auth/callback"

# 2. Grant required scopes
octo-cli -c AddScopeToClient -id "my-dashboard" -n "octo_api"

# 3. Verify the client
octo-cli -c GetClients

The application can now authenticate users via Authorization Code + PKCE and call all OctoMesh APIs.