Registering an application
Everything the Maximus authorization server needs in order to register your application, and what you receive in return.
Applications must be registered with the Maximus authorization server before they can request an access token. Registration is a manual review process; there is no open dynamic client registration endpoint.
Registration is free of charge. Reading this documentation, registering an application and calling the certified API capabilities carry no fee. See the API terms and conditions.
How to register
- Submit the registration request form with the details below.
- Maximus reviews the request. You will be contacted if anything needs clarifying.
- On approval you receive a
client_id, and aclient_secretif your application is confidential.
Attributes required to register
These are the technical attributes the authorization server needs. Supplying them all at the outset avoids a round trip.
Identification
| Attribute | Data type | Required | Notes |
|---|---|---|---|
| Application name | string | Required | Shown to the user on the authorization screen. Must not impersonate another organisation. |
| Organisation name | string | Required | The legal entity responsible for the application. |
| Technical contact | string | Required | Name and email address. Used for security notifications. |
| Intended use | string | Required | What the application does and which users it serves. |
| Application logo | uri | Optional | Displayed on the authorization screen if supplied. |
Technical configuration
| Attribute | Data type | Required | Notes |
|---|---|---|---|
| Client type | enum | Required | public or confidential. See the guidance below — this choice is security-critical. |
| Redirect URI(s) | array<uri> | Required | One absolute URI, matched exactly on every authorization request. Tell us on the request form if your application needs more than one. |
| Launch type | enum | Required | standalone or ehr — one per registration. An application that supports both is registered twice, so that neither client holds a context scope it does not use. |
| Grant types | array<string> | Required | authorization_code, and refresh_token if you need offline access. client_credentials for backend services. |
| Requested scopes | array<string> | Required | The scopes your application needs. Request the minimum. See supported scopes. |
| JWKS or JWKS URI | object / uri | Conditional | Required only if you will authenticate with private_key_jwt. |
| Access token lifetime | integer | Optional | A request, not a guarantee. The granted lifetime is returned as expires_in. |
| Refresh token lifetime | integer | Optional | Applies only when offline_access is granted. Platform default is 90 days. |
Choosing a client type
This is the single most important registration decision, because it determines whether your application can hold a secret.
| Client type | Use when | Authentication |
|---|---|---|
confidential | Your application runs on a server you control, and can keep a secret away from the end user. | client_secret_basic, client_secret_post or private_key_jwt |
public | Your application runs on the user's device or in their browser — a native mobile app, a desktop app or a single-page web app. | None. Identity is proven by PKCE and the registered redirect URI. |
A native application binary or a browser bundle can be decompiled or read. A
secret shipped inside one is not a secret. Register such applications as public and
rely on PKCE, which is designed for exactly this case. Maximus requires S256 PKCE on
every authorization code flow, public or confidential.
Native applications
Native applications should follow RFC 8252, OAuth 2.0 for Native Apps. Register one of these redirect URI forms:
| Form | Example | Notes |
|---|---|---|
| Claimed HTTPS URI | https://app.example.com/oauth/callback | Preferred. Verified by the operating system against your domain, so another app cannot claim it. |
| Private-use URI scheme | com.example.app:/oauth/callback | Acceptable. Use a scheme derived from a domain you control. |
| Loopback interface | http://127.0.0.1:{port}/callback | For desktop applications. The port may vary at runtime. |
Authorization must be performed in the system browser or an in-app browser tab, not an embedded web view. An embedded web view lets the host application observe the user's credentials, which defeats the purpose of the redirect.
What you receive
| Value | Issued to | Handling |
|---|---|---|
client_id | All clients | Not secret. It appears in authorization URLs and may be visible to users. |
client_secret | Confidential clients only | Secret. Store server-side, never in source control, never in a client-side bundle. |
Contact Maximus immediately so the secret can be regenerated. A regenerated secret invalidates the previous one at once, so deploy the replacement promptly.
Changing a registration
Registered client configuration — scopes, redirect URIs, grant types and client type — is change-controlled. Submit changes through the same contact route rather than expecting to edit them yourself. This protects every registered application from unreviewed changes to its security posture.