Overview
The Connected Apps module lets external applications (portals, ERPs, BI tools, .NET middleware, integration scripts…) authenticate against the Cirrus Shield REST API without storing a human user’s password. Before writing any code against the REST API (covered in the next section), your integration must be registered as a Connected App.
Accessing Connected App management
Navigation: Configuration → Connected Apps
This page lists every OAuth application registered for your organization, with its status (active/inactive) and last-used date. This is where an administrator creates a new app, or edits/disables/deletes an existing one.
Creating a Connected App
From the list page, click New App.
Required fields (common to both client types):
| Field | Description |
|---|---|
| Name | Name shown on the consent screen. Max 100 characters. |
| Client Type | Confidential or Public — see “Client Types” below. |
| Allowed Scopes | Permissions granted to the application — see “Available Scopes” below. |
Additional fields for a Confidential client:
| Field | Description |
|---|---|
| Associated User | Cirrus Shield account that provides the data context for machine-to-machine (M2M) calls. |
| Allowed IPs | Optional — list of IPs or CIDR ranges allowed to call the token endpoint. |
| Access Token Lifetime | Validity in seconds. Default: 3600s. Maximum: 86400s. |
Additional fields for a Public client:
| Field | Description |
|---|---|
| Redirect URIs | One URI per line. Exact match required — no wildcards. |
| Access Token Lifetime | Default: 900s (15 min) for the user flow. |
| Refresh Token Lifetime | Default: 604800s (7 days). Maximum: 2592000s. |
Client secret: after creating a Confidential client, the secret is shown only once. Copy it immediately — it cannot be retrieved afterwards. Format: cs_ followed by 40 base64url characters (e.g. cs_rxm2doH1mPQ28NWKbXIlCYImdOrHUXW5HiIGd0Vx). A Public client has no secret — PKCE replaces it.
Client Types
Confidential Client (Machine-to-Machine) — for server-side applications that authenticate without user interaction: scripts, scheduled jobs, backend integrations.
- Has a
client_secretstored server-side. - Uses the Client Credentials flow.
- Acts with the rights of the configured Associated User.
- Cannot use the Authorization Code flow.
Public Client (user delegation) — for web portals or mobile apps acting on behalf of a real Cirrus Shield user.
- No secret (PKCE stands in for proof of possession).
- Uses the Authorization Code + PKCE flow.
- Acts with the rights of the user who consented.
- Issues refresh tokens when
offline_accessis among the scopes.
Available Scopes
| Scope | What it allows |
|---|---|
api:read | Read records (Query, Describe) |
api:write | Create and update records, send emails, generate documents |
api:delete | Delete records |
api | Full API access (equivalent to api:read + api:write + api:delete) |
offline_access | Obtain a refresh token (Authorization Code flow only) |
ℹ️ Scopes granted to the application only set the maximum possible permissions — the associated user (Confidential) or the logged-in user (Public) can still be further restricted by their own profile.
Managing an existing Connected App
From the client’s detail page:
- Enable / Disable — a disabled client returns
401 invalid_clienton every token attempt. - Regenerate Secret — immediately invalidates all of the client’s active tokens, then generates a new secret shown only once. The old secret stops working right away.
- Delete — revokes all active tokens and permanently removes the client.
Activity Log
Each client’s detail page shows the last 20 OAuth events:
| Event Type | Meaning |
|---|---|
TOKEN_ISSUED | Token successfully issued |
TOKEN_REFRESHED | Token renewed via refresh token |
TOKEN_REVOKED | Token revoked (manually or by rotation) |
AUTH_FAILED | Authentication failure — shown in red |
INTROSPECT | Token verified by a Resource Server |
No token or credential ever appears in the logs — only metadata (source IP, duration, HTTP status) is recorded.
Security Best Practices
- Never share a
client_secretacross multiple applications — create one client per application. - Restrict allowed IPs for M2M clients that have a fixed IP.
- Grant each application the minimum scopes it needs.
- Monitor
AUTH_FAILEDevents — a high count can indicate an attack attempt. - Regenerate the secret immediately if compromise is suspected.
- Disable rather than delete an application that’s temporarily out of service (logs are preserved).
Once the Connected App is created, obtaining and using OAuth 2.0 tokens (endpoints, the Client Credentials and Authorization Code + PKCE flows, introspection, JWT validation, code samples) is covered in the next section: 1. AuthToken.
