Create application — step-by-step
Register a ChainIT OAuth application from the Developer Portal UI. The portal walks you through choosing an application type, filling the fields that type needs, picking scopes when relevant, and configuring branding or token policies before you copy the clientId and clientSecret.
Complete Getting Started — sign in to the portal with QR.
Read Application types so you know whether you need M2M, IDP, or Hosted UI — each type asks for a different set of fields.
Your portal user needs the developer or organization admin role to see the Create application action.
Steps
1. Sign in to the Developer Portal (QR)
Open the portal, scan the QR code with the ChainIT mobile app, and approve the session. You land in an authenticated console scoped to your organization. See Developer Portal — Getting Started for the full walkthrough.
2. Open Applications and start a new one
From the portal navigation, open the Applications section and choose Create / Register application. You will be asked to pick an application type first — that choice drives every field that follows.
3. Select the application type
Pick the type that matches what you are building. Use the matrix on Application types if you are unsure.
| Type | Choose it when |
|---|---|
| M2M | A backend service needs to call ChainIT REST APIs (no end-user login). |
| IDP | You want a “Login with ChainIT” button in your own UI (OAuth 2.0 / OIDC + PKCE). |
| Hosted UI | You want a fully managed, ChainIT-hosted onboarding UI (OTP, terms, face liveness, ID capture) styled with your branding. |
4. Fill in the details for that type
The form only shows fields that apply to the type you picked. Fill them with values from your product.
| Type | Fields you will see |
|---|---|
| M2M | Name, Description, Scopes (API permissions), optional Token management (expiration). |
| IDP | Name, Description, Redirect URLs, Allowed web origins (required, no *), Scopes (OIDC), Token management (expiration, refresh-token rotation). |
| Hosted UI | Name, Description, Allowed web origins (required, no *), Branding (logo, colors, brand name, font), optional Token management. |
5. Select scopes (optional, depending on type)
| Type | Scope behaviour |
|---|---|
| M2M | Pick the API permissions your service needs (for example FILE_UPLOAD, MINTING). Follow least-privilege — see Scopes overview. |
| IDP | Choose OIDC scopes (openid is required; add profile, email, phone as needed). |
| Hosted UI | No scope picker — the hosted flow manages scopes for you. |
You can change the scope set later from the same Applications screen without rotating credentials.
6. Configure as per the type
Use the type-specific sections in the portal to finish the setup:
| Type | What to configure |
|---|---|
| M2M | Token lifetime under Token management if the org default does not fit your usage. To publish the app to the marketplace, also set Visibility and Mode — see below. |
| IDP | Set URL White Listing (CORS) with at least one allowed origin (one per line, no *). Token lifetime and refresh-token rotation (see Refresh tokens — rotation). Keep redirect URLs and origins exactly matching your deployed app. |
| Hosted UI | Set URL White Listing (CORS) first with at least one allowed origin (one per line, no *). Hosted UI does not use callback/redirect URLs. Then open the Branding tab and set your logo, primary / secondary colors, brand name, and font. Optionally override per-screen titles and button labels. See Hosted UI — Branding customization. |
Visibility & Mode
M2M apps only. If you intend to make the app installable, two extra properties decide who can find it and how installs get approved. Set them here while configuring the app (or before publishing). They do not apply to IDP or Hosted UI apps.
Visibility controls who can see the app:
| Visibility | Who can see it | Installable |
|---|---|---|
| Private | Only the owner organization. | No — internal use only. |
| Public | Every organization, via the global marketplace. | Yes — any org can install. |
| Partner | Only organizations in the selected business groups. | Yes — by invitation. |
Mode controls how a Public app's installs get approved:
| Mode | Behaviour |
|---|---|
| Auto | Installs are approved automatically and go live immediately. |
| Manual | Installs require explicit owner approval before they activate. |
A few things to keep in mind:
Visibility and Mode are set once when the app is created and cannot be changed afterwards.
Choose carefully before saving.
Mode applies to Public apps only. Private apps are never installable, and Partner apps always require the invited organization to accept — there is no Auto/Manual choice for them.
Private apps never enter the installation lifecycle. Use this for backend services you run inside your own organization.
Once the app is live, these choices drive the whole install experience — see
Installable Applications
for each flow end to end.
7. Save and copy credentials
When you save, the portal shows the new application with its clientId and, for confidential clients, the clientSecret — usually only once. Copy them into a password manager or secret store (cloud secret manager, CI sealed secrets, or server-side .env files that are never committed). See Retrieve and store credentials.
Do not embed clientSecret in SPAs, mobile binaries, or public
repositories. Hosted UI and M2M always use the secret on a
server; IDP public clients use PKCE instead of shipping a
secret to the browser. See
Security best practices.