identity.yaml Schema (v1)

The identity.yaml file is the declarative configuration for an application's identity and role structure in Conservice Console AuthX. Placing a file at .stratus/identity/<environment>/identity.yaml in your application's repository provisions the corresponding group structure in Keycloak and makes the application queryable through the Portal User Manager GraphQL API.

One file is required per environment:

.stratus/
  identity/
    development/
      identity.yaml
    staging/
      identity.yaml
    production/
      identity.yaml

Schema URL — major version v1

https://schemas.conservice.com/identity/v1/identity.yaml.schema.json

Add to .vscode/settings.json for IDE auto-validation and autocomplete:

{
  "yaml.schemas": {
    "https://schemas.conservice.com/identity/v1/identity.yaml.schema.json": ".stratus/identity/**/identity.yaml"
  }
}

Contents

• Top-level fields
• roles
• taskServiceSources
• myApps
  • myApps.subRoutes
• Schema versioning
• Where to file requests
• Cross-references

Top-level fields

Field	Type	Required	Notes
displayName	string	No	Human-readable display name for the application. Defaults to the GitHub repository name if not set.
allowExternalUsers	boolean	No	If true, users outside the conservice.com domain are permitted to access the application. Defaults to false.
roles	array	No	Application-specific roles that control access to features. See roles.
taskServiceSources	array of strings	No	Task Service source IDs for applications that integrate with Task Service. See taskServiceSources.
myAppsCallbackUrl	string (URI)	No	Endpoint that returns this application's My Apps menu configuration dynamically. Mutually exclusive with myApps — if both are present, myApps is ignored with a warning. Must use http or https on an approved company domain.
myApps	object	No	Static My Apps menu configuration. Ignored if myAppsCallbackUrl is set. See myApps.

The schema enforces additionalProperties: false at every level. Unrecognised fields produce a validation error.

roles

Each entry in roles defines an application-specific access role. The role name is the stable key used in application code and in Portal User Manager GraphQL queries.

Field	Type	Required	Notes
name	string	Yes	Stable identifier for the role. Pattern: ^[A-Za-z][A-Za-z0-9_-]*$. Common case formats are all valid: PascalCase, camelCase, snake_case, kebab-case, SCREAM_CASE. Must be unique within the application.
displayName	string	No	Human-readable label shown in admin UIs. Defaults to name if not set.
displayOrder	integer ≥ 1	No	Sort position in role listings. Roles without a displayOrder appear last, sorted alphabetically by displayName.

caution

Do not store the id field returned by the Portal User Manager GraphQL API. It is a Keycloak UUID that differs per environment and can change. Use name as the stable key in your application code and database.

Example:

roles:
  - name: Administrator
    displayName: 'Administrator'
    displayOrder: 1
  - name: read-only
    displayName: 'Read Only'
    displayOrder: 2
  - name: auditor
    displayName: 'Auditor'

taskServiceSources

An array of Task Service source identifiers for applications that integrate with Task Service. Each value must match ^[A-Za-z][A-Za-z0-9_-]*$.

taskServiceSources:
  - BILLING_TASKS
  - AUDIT_TASKS

myApps

Controls how the application appears in the Portal "My Apps" menu. Two approaches are supported and are mutually exclusive: a callback URL for dynamic menus, or a static configuration block. An application that specifies neither does not appear in the My Apps menu.

Callback URL (dynamic)

Set myAppsCallbackUrl to a service endpoint that returns menu items at runtime. The Console host shell calls this URL for each authenticated user. The URL must use http or https and its hostname must be a subdomain of an approved company domain.

myAppsCallbackUrl: 'https://my-app.conservice.com/api/my-apps'

When a callback URL is set, any myApps block in the same file is ignored and a warning is emitted during ingestion.

Static configuration

Set myApps when the application has a fixed path and optional sub-navigation.

Field	Type	Required	Notes
path	string	Yes	Path for the My Apps link (e.g. /my-application).
displayText	string	No	Link label. Defaults to the application displayName if not set.
subRoutes	array	No	Sub-navigation links within this application's My Apps entry. See myApps.subRoutes.

myApps:
  path: '/my-application'
  displayText: 'My Application'

myApps.subRoutes

Sub-routes appear as secondary links within the application's My Apps entry. They are rendered in the order they are declared in the YAML file.

Field	Type	Required	Notes
path	string	Yes	Path for the sub-route link.
displayText	string	Yes	Display text for the sub-route link.
displayOrder	integer	No	Deprecated. Accepted for backward compatibility but ignored. Declaration order determines render order.
permittedRoles	array of strings	No	Role name values whose holders can see this sub-route. If omitted, all users with access to the application see the link.

myApps:
  path: '/my-application'
  subRoutes:
    - path: '/my-application/admin'
      displayText: 'Administration'
      permittedRoles:
        - Administrator
    - path: '/my-application/reports'
      displayText: 'Reports'

Schema versioning

This document covers major version v1 of the identity.yaml schema.

Concept	Meaning
URL major version (v1)	The published schema contract at schemas.conservice.com. Incremented only on breaking changes. All previous major versions remain available permanently.
Within-major updates	Non-breaking additions — new optional fields, relaxed constraints — are applied in-place without changing the major version or the URL.

Breaking changes (removing a field, narrowing a constraint, changing a field type) result in a new URL path (/identity/v2/, etc.) while /identity/v1/ stays live.

Where to file requests

Schema changes and new feature requests are handled by the Portal team.

• New fields or capabilities — open a ticket describing the use case and the consuming application
• Constraint changes — include the current constraint, the desired change, and why
• Documentation corrections — a ticket or a PR to this doc are both welcome

Cross-references

Resource	Reference
JSON Schema artifact	identity.yaml.schema.json
Keycloak group structure	KeycloakGroupStructure.md in the internal platform-portal-user-manager repo — reach the Portal team for access
Portal User Manager GraphQL API	Internal-only — reach the Portal team for the endpoint and service-account credentials