Aggregated open metadata endpoint to be used in orchestrated user flows

[brionmario]

Problem

Currently, different parts of our application rely on multiple endpoints to fetch metadata required for user journeys (i.e sign-in, sign-up & recovery).

For example:

• Theming information is retrieved via the resolved Branding API, which requires hierarchical resolution.
• Internationalization strings are fetched separately via the i18n API, with namespace and hierarchy resolution.
• Application-specific settings like whether self-registration is enabled, or the application name, logo must be retrieved from the Applications API.
• Organization-Unit-specific settings like whether self-registration is enabled, or the organization name, logo must be retrieved from the OU API.

ex:

This leads to multiple network requests during sign-in, sign-up, and recovery flows, increasing latency and complexity in the front-end code. It also makes consistent resolution of themes, i18n, and application settings challenging.

Also, if a developer wants to build their own portals with our APIs rather than using the SDKs, this will not provide a good DX.

Important

The current /branding API is primarily focused on theming (colors, layouts, visual preferences) rather than comprehensive branding (which typically includes brand identity, guidelines, and marketing assets). The term "branding" may be misleading - we're actually managing UI themes and visual presentation configurations.

Why is this needed

An aggregated endpoint for sign-in, sign-up, and recovery flow metadata would:

1. Reduce network overhead: By combining themes, layouts, i18n, application settings, and OU settings in a single response, we reduce the number of requests needed on the front end.
2. Ensure consistency: Hierarchical resolution (Organization → Organizational Unit, B2B scenarios, etc.) for themes and i18n can be centrally handled, ensuring that the front-end always gets a consistent, ready-to-use response.
3. Improved DX: For developers building custom authentication experiences using Thunder APIs, they can rely on one unified metadata endpoint instead of orchestrating multiple API calls.
4. Simplified caching: A single endpoint makes it easier to implement effective caching strategies for authentication flow metadata.
5. Theme and layout selection support: Returns all available themes and layouts with their full definitions, allowing for theme/layout selection dropdowns in the UI.
6. Reference-based architecture: Applications and OUs reference themes and layouts by ID, while the full definitions are provided in the response for efficient client-side resolution.

Proposed Solution

Introduce a new aggregated endpoint that provides all necessary metadata for authentication flows in a single request. The response includes application and OU references to themes and layouts, along with the complete definitions of all available themes and layouts.

Sample API Structure

GET /flow/meta?app_id=550e8400-e29b-41d4-a716-446655440000&language=en&namespace=login,common

Query Parameters

Parameter	Description	Required	Example
app_id	Application identifier	Yes	550e8400-e29b-41d4-a716-446655440000
language	Language code for translations (ISO 639-1)	No	en, es, fr
namespace	Comma-separated i18n namespaces	No	login,common,recovery

Response

{
  "is_registration_flow_enabled": true,
  "application": {
    "id": "60a9b38b-6eba-9f9e-55f9-267067de4680",
    "name": "My Web Application",
    "logo_url": "https://myapp.example.com/logo.png",
    "url": "https://myapp.example.com",
    "tos_uri": "https://myapp.example.com/terms",
    "policy_uri": "https://myapp.example.com/privacy",
    "cookie_policy_uri": "https://myapp.example.com/cookies"
  },
  "ou": {
    "id": "fe447a2f-29c5-4e33-ac8f-d77be15fdb32",
    "handle": "default",
    "name": "Default Organization Unit",
    "logo_url": "https://myapp.example.com/logo.png",
    "tos_uri": "https://myapp.example.com/terms",
    "policy_uri": "https://myapp.example.com/privacy",
    "cookie_policy_uri": "https://myapp.example.com/cookies"
  },
  "design": {
    "theme": {
        // resolved layout
    },
    "layout": {
        // resolved layout
    }
  },
  "i18n": {
    "languages": [
        "en-US",
        "fr-FR"
    ],
    "language": "en",
    "translations": {
        // translate strings
    }
  }
}

Response Structure Explanation

• application.themes: Array of theme IDs configured for this application
• application.layout: Layout ID configured for this application
• ou.themes: Array of theme IDs configured for the organizational unit
• ou.layout: Layout ID configured for the organizational unit
• design.layouts: Array containing full definitions of all available layouts (referenced by application/OU)
• design.themes: Array containing full definitions of all available themes (referenced by application/OU)

This reference-based approach allows:

1. Applications and OUs to specify which themes/layouts they support
2. Clients to resolve the full definitions by looking up IDs in the design arrays
3. Efficient hierarchical resolution (OU themes can be merged with application themes)
4. Flexibility for theme/layout selection UIs

Benefits

• Single endpoint: Reduces complexity in client implementations
• Hierarchical resolution: Server-side resolution ensures correct theme and i18n inheritance
• Performance: Fewer round trips improve load times for authentication flows
• Consistency: Guaranteed consistent state across application metadata, OU settings, themes, layouts, and translations
• Theme and layout flexibility: Returns all available themes and layouts for user selection via dropdown/switcher
• Reference-based architecture: Efficient ID-based references from application/OU to themes and layouts, with full definitions provided for client-side resolution
• Complete theme support: Includes light/dark color schemes, typography, spacing, and shape configurations for full UI theming support
• Layout customization: Multiple layout options (centered, left-aligned, etc.) can be configured per application or OU
• Future-proof: Can be extended to include additional metadata (feature flags, auth flow configs, etc.)

Implementation Notes

• The existing /branding, /application, /ou, and /i18n APIs will continue to exist for management operations (CRUD)
• This new endpoint is specifically designed for runtime/presentation purposes
• The endpoint should support public access (pre-authentication) with appropriate CORS policies
• Response should be cacheable with appropriate cache headers
• Clients should resolve theme and layout references by looking up IDs in the design.layouts and design.themes arrays
• Hierarchical resolution logic:
  • Application themes take precedence over OU themes
  • Application layout takes precedence over OU layout
  • Client can implement theme switching by allowing users to select from available themes
• User's theme preference (selected theme) will be managed separately and applied client-side
• Each theme includes complete color schemes (light/dark), typography, spacing, and shape configurations for full UI theming support
• Each layout includes complete screen definitions with slots, positioning, sizing, and component arrangements

[senthalan]

I have one concern on the same response object, 'is_registration_flow_enabled' is part of the ou and application. So we are expecting the client to perform logic programming to check whether the registration is enabled or not. I think this is not correct. The backend should return resolved values.

[senthalan]

And any specific reason for having themes and layout under ou and application?

Can applications' theme and ous' theme different ?

Same as my inital comment, there should be one set of resolved themes returned from the backend

[brionmario]

Thanks for pointing this out.
Makes sense.

Updated the JSON! 🙌

[ThaminduDilshan]

As per our current design, allowing registration is defined by application and the user type (schema). Applications have their allowed user types in the application configs. Does this backend resolution mean checking for both the below options?

1. Checking for the application's registration enabled config
2. Checking whether at least one allowed user type has self registration enabled

I believe answer for this is YES. Please note this for the implementation

[brionmario]

Ack.
Also one question, will we have a is_registration_flow_enabled config for OU level in the future?