Customize the sign-in experience
Brand the SenseCrypt sign-in page per OIDC application — organization name, primary and accent colors, and a logo you upload — so users see your identity, not a generic prompt.
When a user signs in through SenseCrypt, they land on a hosted email-entry / sign-in page before the on-device biometric ceremony takes over. That page can wear your identity — your organization name, colors, and logo — so the user knows exactly which app they're signing in to. Branding is configured per OIDC application, so each app you register can present its own look.
This guide covers what you can customize and how to set it, including uploading a logo.
What you can brand
Every OIDC app has an optional branding configuration. All fields are optional — leave one unset and SenseCrypt falls back to a sensible default.
| Field | What it controls | Notes |
|---|---|---|
org_name | The organization name shown on the sign-in page. | Falls back to the application's name if you don't set it, so the page is never blank. |
primary_color | The primary brand color. | A hex color in #RRGGBB form (six digits). Defaults to SenseCrypt's own primary. |
accent_color | The accent/secondary color. | Same #RRGGBB format. Defaults to SenseCrypt's own accent. |
icon_logo_url | A compact square logo (icon mark). | A URL — typically one you get back from the logo upload endpoint. |
full_logo_url | A wider wordmark/full logo. | When present, it's preferred over the icon on the sign-in page; the icon is used where a compact mark fits better. |
short_message | A brief line of text shown alongside the sign-in prompt. | Up to 80 characters. |
A few rules worth knowing:
- Colors must be
#RRGGBBhex. Three-digit shorthand, named colors, andrgb(...)are rejected — use the full six-digit form. org_namehas a floor. If you clear it, the app's own name is used, so the branded page always shows something recognizable.- Logos come from URLs. You can point at an externally hosted image, but the built-in upload endpoint is the intended path — it validates and stores the image for you and hands back a URL to drop straight into
icon_logo_urlorfull_logo_url.
Setting an app's branding
Branding lives on each OIDC application and is managed through the admin console (or the Management API). Read the current configuration and update it:
- Read —
GET /v1/admin/oidc-apps/{client_id}/brandingreturns the app's branding config. - Update —
PUT /v1/admin/oidc-apps/{client_id}/brandingreplaces it with the fields you send.
These operations require the branding:read and branding:update capabilities respectively, so an admin (or M2M app) needs those in its role to view or change branding. See the API reference for the exact request and response shapes.
Because PUT replaces the whole configuration, send the full set of fields you want to keep — omitting a field clears it (and it reverts to its default).
Uploading a logo
To use your own logo, upload the image first and then reference the returned URL in your branding config.
Endpoint: POST /v1/admin/uploads/logo (multipart file upload; requires an admin session).
Accepted formats: PNG, JPEG, WebP, and SVG.
Limits:
- Up to 2 MB per file.
- Up to 2048 × 2048 px (both raster images and sized SVGs are checked against this cap).
The upload is validated on the way in — raster images are verified as well-formed, and SVGs are parsed and sanitized down to safe, presentational markup (script-bearing and external-loading constructs are stripped), so an uploaded SVG can't carry active content onto the sign-in page.
The response contains a URL for the stored image. Uploads are content-addressed by the image's hash, so re-uploading the same file is idempotent — you get the same URL back and no duplicate is stored. Take that URL and set it as icon_logo_url (for a square mark) or full_logo_url (for a wordmark) in the app's branding, using the update operation above.
A typical flow:
POST /v1/admin/uploads/logowith your logo file → receive a URL.PUT /v1/admin/oidc-apps/{client_id}/brandingwith that URL set onfull_logo_url(and/oricon_logo_url), along with yourorg_nameand colors.- Start a sign-in against that app and confirm the branded page shows your identity.
Where branding shows up
Your branding is applied to the branded email-entry / sign-in page that a user sees when they begin an OIDC sign-in for that application — the page that collects their email and hands off to the on-device biometric ceremony. The org_name, colors, and logo are what tell the user they're signing in to your app rather than a generic prompt.
Branding is a presentation layer only. It does not change the protocol, the tokens you receive, or the security model — it's purely how the sign-in experience looks. For what happens after the branded page, see How SenseCrypt works.
Related
- Add Login (OIDC) — register an app and wire up sign-in, the app you'll then brand.
- How SenseCrypt works — the sign-in ceremony the branded page begins.
- API reference: OIDC apps — the branding and upload operations in full.
Groups and access
Control who may sign in to each application with SenseCrypt's default-closed group-to-app access gate — attaching groups, managing membership, and understanding eager revocation.
Refresh tokens and sessions
Keep users signed in with SenseCrypt refresh tokens — requesting offline_access, handling rotation and reuse detection, revoking sessions, and implementing logout without a server-side SSO cookie.