App management

Overview

App management in cidaas provides a central place to configure and manage OAuth2/OIDC clients. These clients may represent portals, mobile applications, backend services, or third-party clients.

cidaas implements OAuth2 and OpenID Connect (OIDC), ensuring secure, standards-based authentication and authorization for all applications.

Where to configure

Platform	Location
Trustdesk (cidaas 4.x)	Integrations → Applications
Legacy Admin Dashboard	Apps → App Settings (transition period only)

Trustdesk consolidates application configuration under Integrations. Related settings live in other sections — configure shared dependencies first, then create the application. See Introducing Trustdesk for the full Admin Dashboard → Trustdesk mapping.

Typical App Developer workflow in Trustdesk

• Integrations → Applications — register and configure OAuth2/OIDC clients
• Integrations → Endpoints — verify discovery URLs when wiring SDKs
• Permission Setup → Scopes — define and assign client permissions (Scope management)
• Providers → Identity Providers — enable login providers per application
• Branding → Hosted Pages Groups — reference hosted page groups for login and registration

Prerequisites

Before creating an app in cidaas, ensure the following:

• Access to Trustdesk (or the Admin Dashboard during transition) with app management permissions (APP_CREATE, APP_MANAGER, or equivalent admin role in the CIDAAS_ADMINS group).
• Redirect URLs and logout URLs are prepared.
• Required scopes and API resources are already created.
• Hosted page group or login providers are configured (if needed).
• Company details such as Terms & Conditions and Privacy Policy URLs are available.
• For mobile apps: package name / bundle ID and redirect scheme are ready.

External dependencies

Dependency	Configure in Trustdesk	Why it matters
Field definitions	User Setup → Field Setup	Tenant-wide field keys, types, and validation used across registration and profile flows
User Setup profile	User Setup	Per-application allowed/required fields, login identifiers, and registration behaviour (linked via user_setup_id). See User Setup.
Hosted page groups	Branding → Hosted Pages Groups	Login, registration, and verification page URLs referenced from a layout
Hosted page layout	Branding → Hosted Pages Layout	Branding and layout settings per application (linked via hosted_pages_layout_id)
Identity providers	Providers → Identity Providers	Providers must exist before they can be enabled on an application

Operational tip
Create shared configuration (user fields, hosted pages, providers, scopes) before provisioning applications under Integrations → Applications.

Key benefits

1. Standardized and secure authentication using OAuth2/OIDC.
2. Centralized permission and scope management for all apps.
3. Separation of authentication from applications, with cidaas acting as the authorization server.

Note
App settings define the authentication behavior, UI customization, system rules, permissions, and required user information for an application.

App configuration model

The application document (Apps_AppConfiguration) is the central record in Integrations → Applications. Settings fall into two groups:

• Inline on the application — OAuth2/OIDC behaviour, redirect URIs, client secrets, token lifetimes, and similar values stored directly on the app record.
• Referenced from Trustdesk — shared setup created in other Trustdesk sections and linked by ID (for example user_setup_id, hosted_pages_layout_id). The application stores the reference; the full configuration lives in User Setup, Branding, Permission Setup, and so on.

┌─────────────────────────────────────────────────────────────────┐
│                   APP CONFIGURATION MODEL                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────┐   references (IDs)   ┌─────────────────┐  │
│  │   Application    │◄────────────────────►│ Trustdesk shared│  │
│  │  (OAuth2 client) │                      │     setup       │  │
│  └──────────────────┘                      │                 │  │
│         │                                  │ User Setup      │  │
│         │                                  │ (Field Setup)   │  │
│   inline│                                  │ Hosted Pages    │  │
│   OAuth2│                                  │ Scopes          │  │
│   config│                                  │ Identity Prov.  │  │
│   on app│                                  │ Verification,   │  │
│         │                                  │ Consent, …      │  │
│         │                                  └─────────────────┘  │
│         │                                                       │
│         │ login / token issuance (runtime)                      │
│         ▼                                                       │
│  ┌──────────────────────┐                                       │
│  │ Access / ID token    │  claims from allowed scopes +         │
│  │ (issued to client)   │  fields linked via User Setup         │
│  └──────────────────────┘                                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key relationships

• Application ↔ Trustdesk shared setup: The app links to shared records by ID. Configure field definitions under User Setup → Field Setup, registration profiles under User Setup, hosted page groups under Branding → Hosted Pages Groups, layouts under Branding → Hosted Pages Layout, scopes under Permission Setup, and so on — then reference those IDs on the application.
• Application → Inline config: Grant types, redirect URIs, client secrets, token lifetimes, branding overrides, and group restrictions are stored directly on the application document.
• Application → Scopes: The app declares allowed_scopes and default_scopes. Only scopes assigned to the client can be requested at login.
• Shared setup → Token claims: At login, cidaas merges the application config with linked User Setup and scope mappings to build access and ID token claims.

External reference fields

Some application fields store only an ID reference. app-srv does not own the full configuration — it stores the ID and invalidates app caches when shared setup changes.

App field	Service	Entity	Resolve with	Trustdesk
user_setup_id	user-srv	UserAppSetup	GET /user-srv/usersetup/{id}	User Setup
hosted_pages_layout_id	hostedpages-srv	HostedPageLayoutEntity	GET /hostedpages-srv/hosted-page-layouts/{id}	Branding → Hosted Pages Layout

There is no hosted_pages_id on the application. Hosted page groups are linked indirectly: a layout's layout.hosted_page_group field points to a Hosted Page Group, and the application stores the layout ID.

Registration fields (three layers)

1. Field Setup (fieldsetup-srv) — defines field keys, types, and validation tenant-wide.
2. User Setup (user-srv) — profile that selects allowed_fields, required_fields, login identifiers, and registration rules. Field keys must exist in Field Setup.
3. Application (app-srv) — stores user_setup_id pointing to the User App Setup record.

Recommended workflow

1. Create Field Setup field definitions.
2. Create a User Setup profile referencing those field keys.
3. Create a Hosted Page Group, then a Hosted Page Layout that references the group (Hosted Pages Management).
4. Create or update the application via App Configuration API, setting user_setup_id and hosted_pages_layout_id.

See Configuration sections for the full section map and Field settings for how scopes connect fields to token claims.

What applications do

An application (OAuth2/OIDC client) is the central integration point between your software and cidaas. Depending on its type and configuration, it can:

Capability	Description
Authenticate users	Run login flows on hosted pages or via SDK/API, with social, SAML, OIDC, or directory providers
Register users	Collect registration fields, progressive profiling, and account verification
Issue tokens	Return authorization codes, access tokens, ID tokens, and refresh tokens according to configured grant and response types
Enforce access rules	Restrict login by groups/roles, require MFA or step-up verification, and collect scope or legal consent
Authorize API access	Limit which scopes and resources the client can request; downstream APIs validate those scopes
Customize user-facing UI	Brand login/registration pages via hosted page groups, layouts, colors, and logos
Machine-to-machine access	Act as a confidential client using the client credentials flow (Non-Interactive type)

Not every capability applies to every application type. For example, Non-Interactive and Device clients skip hosted-page and registration settings; Third Party clients always require scope consent. See Application types and Availability by app type.

Configuration sections

See Application types for client_type values, OAuth flows, and configuration availability by type.

When you open an application in Integrations → Applications, settings are grouped into sections. The table below is the recommended map for administrators and integrators: what each area controls, where shared configuration lives in Trustdesk, and where to read more.

Section	What you configure	Configured on the app	Shared config in Trustdesk	Learn more
General	App name, display name, type, enabled state, OAuth standard	✅	—	App details
Branding & hosted pages	Logo, colors, background, layout alignment; reference to hosted page layout (which links to a hosted page group)	✅ (hosted_pages_layout_id)	Branding → Hosted Pages Groups, Hosted Pages Layout, Theming	Hosted Pages
OAuth2 / OIDC	Grant types, response types, redirect URIs, logout URLs, web origins, PKCE, PAR, DPoP, CIBA	✅	—	OAuth2 flows
Client authentication	Client ID, client secrets, token endpoint auth method	✅	—	Secret & key rotation
Scopes	Allowed and default scopes the client may request	✅ (assignment)	Permission Setup → Scopes, Scope Groups	Scope management
Token settings	Access, ID, and refresh token lifetimes; custom access-token claims; JWE encryption	✅	—	Token settings
Company & legal	Company name, address, website, terms, privacy, imprint	✅	—	Company details
Identity providers	Which social, SAML, OIDC, or AD providers are enabled for this app	✅ (selection)	Providers → Identity Providers	Identity providers
Authentication & MFA	Allowed auth methods, passwordless, remember me, guest login, verification options, success pages	✅ (inline + references)	SecureOps → Verification Methods, Verification Options, Suggest Verification	Authentication methods
Registration & fields	Allowed/required fields, registration behaviour, deduplication	✅ (user_setup_id)	User Setup (profile); field keys from User Setup → Field Setup	User Setup
Groups & roles	Login restrictions, default groups, group selection at login, JWT hints	✅	Permission Setup → User Groups, Roles, Group Selection, User Group Verification Filter	Groups & role restrictions
Consent	Consent groups required during login	✅ (references)	Consents → Consents, Consent Groups	Consent management
Communication	Template group for notifications; email/SMS verification requirements	✅ (selection)	Communication → Template Groups	Communication management
Password policy	App-specific password policy override	✅ (reference)	SecureOps → Password Policies	Password policy
Mobile & hybrid	Package/bundle ID, deep links, native-to-web SSO	✅	—	Application types
Signing keys	Active KID and signing key for the client	✅	—	Secret & key rotation

References vs inline config
Many sections store only an ID reference on the application (for example hosted_pages_layout_id, user_setup_id, verification_options_id). The actual configuration lives in the shared Trustdesk section listed above. Create and validate shared config first, then link it on the application.

Tenant defaults

Some authentication defaults apply tenant-wide and are inherited when an application leaves a reference empty:

Default	API	Purpose	Link
Auth setup defaults	GET / PUT /apps-srv/apps/auth-setup-defaults	Tenant-wide defaults for passwordless auth and related authentication setup values	Get · Update

App details

Setting	Description	More information
App name	Internal name displayed in the app overview.	–
App display name	Shown on hosted pages during login and registration.	Hosted Pages Management
App logo URL	Logo displayed on overview and hosted pages.	Hosted Pages Management
Logo position	Sets alignment of the logo (left, center, right).	Hosted Pages Management
Login form position	Aligns the login form on hosted pages.	Hosted Pages Management
Media type	Selects image or video for background.	–
App background URL	Public URL of the custom background.	Hosted Pages Management
App primary color	Primary accent used in UI elements.	Hosted Pages Management
App accent color	Secondary highlight color.	Hosted Pages Management
App type	Determines available configuration options.	See Application types and Availability by app type

In Trustdesk: General settings and branding fields appear when creating or editing an application under Integrations → Applications.

App settings

Core OAuth client settings. Most map to the OAuth2 / OIDC, Scopes, and Client authentication rows in Configuration sections.

Setting	Description
Client ID	Unique identifier generated during app creation.
Client secret	Secret used in flows such as Client Credentials. See Client secret rotation.
Scope	Defines which resources and APIs the client can access. See Scope management.
Hosted page group	Hosted page group used during login and registration.
Redirect URLs	Allowed URLs for returning tokens or authorization codes.
Allowed logout URLs	Allowed redirect URLs after logout.

Company details

Legal and company metadata shown on hosted and profile pages. Maps to the Company & legal row in Configuration sections.

Setting	Description
Company name	Internal reference name.
Company address	Internal reference address.
Website URL	Internal reference website.
Terms and conditions URL	Displayed on hosted and profile pages.
Privacy policy URL	Displayed on hosted and profile pages.
Imprint URL	Displayed on hosted and profile pages.
Description	Additional company-related information.

Developer reference

Application management APIs are served by app-srv under the /apps-srv context path. Authenticated calls require a bearer token with the appropriate OAuth scope (cidaas:apps_read, cidaas:apps_write, or cidaas:apps_delete) and an admin or developer-portal role such as APP_CREATE, APP_READ, APP_DELETE, APP_MANAGER, or APP_VIEWER.

Legacy client APIs

These endpoints operate on the established client model and are fully documented in the App Settings OpenAPI reference.

Operation	Method	Path	Description	Link
Create app	POST	/apps-srv/clients	Creates an app and provisions clients automatically.	View API
Update app (full)	PUT	/apps-srv/clients	Replaces app settings; send all required values.	View API
Update app (partial)	PATCH	/apps-srv/clients/{client_id}	Updates selected fields without sending the full payload.	View API
Get app	GET	/apps-srv/clients/{client_id}	Retrieves an application by client ID.	View API
Delete app	DELETE	/apps-srv/clients/{client_id}	Deletes an application.	View API

App configuration APIs (cidaas 4.x)

Documented in the App Configuration API reference (Apps_AppConfiguration, Trustdesk Integrations → Applications).

Operation	Method	Path	Link
Create app configuration	POST	/apps-srv/apps	View API
List app configurations	GET	/apps-srv/apps	View API
Get app configuration	GET	/apps-srv/apps/{clientID}	View API
Update app configuration	PUT	/apps-srv/apps/{clientID}	View API
Delete app configuration	DELETE	/apps-srv/apps/{clientID}	View API
Graph search	POST	/apps-srv/apps/graph	View API
Get auth setup defaults	GET	/apps-srv/apps/auth-setup-defaults	View API
Update auth setup defaults	PUT	/apps-srv/apps/auth-setup-defaults	View API

Note
Legacy client APIs remain on /apps-srv/clients. Trustdesk and cidaas 4.x use /apps-srv/apps. Both API families target the same underlying applications — prefer the app configuration API for new Trustdesk-aligned integrations.

Related APIs

Topic	Documentation
Client secret rotation	Rotation of secrets and keys
App key (KID) rotation	Rotation of secrets and keys
Scope management	Scope management
Field Setup (field definitions)	Field settings · Field Settings API
User Setup (user_setup_id)	User Setup · User Setup API
Hosted pages & layouts (hosted_pages_layout_id)	Hosted Pages Management · Hosted Pages API

Explore related topics

• User Setup
• Application types
• OAuth2 flows
• OIDC basics
• Client secret rotation
• Scope management
• Hosted Pages Management
• Permission and scope management
• Introducing Trustdesk
• Token structure and settings

Need help?

For assistance, visit our Support Portal.