Guides - NexinID

Guide map

Choose the integration surface

These entry points replace the old anchor-heavy docs page with route-level sections that product pages can link to directly.

Sign-in

Tenant app sign-in

Use Authorization Code with PKCE, tenant-context scopes, userinfo mapping, and JWT validation.

Open sign-in guide

Service client

Service-to-service

Use Automation clients, client credentials, scoped machine access, and SharedAuth service-client helpers.

Open service guide

Marketplace

Marketplace consumption

Discover catalog items, install products, create subscriptions, entitlements, and seat assignments.

Open marketplace guide

Device trust

Device activation

Bind hardware, installation, activation, entitlement, heartbeat, offline lease, and revocation state.

Open device guide

Feature gating

Authorization & entitlement

Gate a feature on RBAC and licensing, use the perm_ver and ent_ver cache signals, and call the authoritative runtime check.

Open feature-gating guide

Device-bound tokens

Proof-of-possession & continuous evaluation

Present a device proof at /connect/token, read the device claims on the access token, and re-check live device trust at resource access with RequireDeviceTrust().

Open device-token guide

Tenant app sign-in

OIDC with PKCE and tenant context

Provision an InteractiveWeb client for browser or native sign-in. PKCE clients do not need a client secret, and they should request only the standard interactive scopes unless an approved integration requires more.

Flow

Authorization Code + PKCE

Use discovery metadata for authorization, token, userinfo, logout, and JWKS endpoints. Configure exact redirect and post-logout redirect URIs.

Request openid, profile, email, tenant_context, and nexidentity.api.
Validate token issuer, audience, signature, lifetime, and scopes before reading claims.
Use tenant_id, organization_id, membership_id, session_id, and perm_ver for tenant-aware runtime behavior.

Service-to-service

Automation clients and protected calls

Use Automation clients for tenant-owned services that call protected APIs. Keep credentials in a secret store and grant only the capability scopes required by the workload.

Prefer SharedAuth client plumbing for .NET services.

Nexin.SharedAuth centralizes token acquisition, bearer-token handlers, compatibility headers, API-version headers, and NexIdentity route helpers. It is currently a NexIdentity integration SDK and still carries LocalIdentity packaging debt until the package split lands.

Marketplace

Install, subscribe, entitle, and assign seats

Marketplace consumption is API-backed today. A consumer organization discovers catalog items, installs a product, creates a subscription and entitlement, then assigns seats to user memberships.

01

Discover eligible products

Call GET /api/licensing/organizations/{orgId}/marketplace/catalog. Eligibility reflects app external-consumption policy, product and edition publication, visibility, and allowlist state.

02

Install the product

Call POST /api/licensing/organizations/{orgId}/product-installations. This creates the cross-tenant bridge from consumer organization to vendor product and edition.

03

Create subscription, entitlement, and seats

Create the organization subscription, create the entitlement under that subscription, then assign seats through PUT /api/licensing/entitlements/{id}/seats.

Gating an installed feature

Once a consumer holds a seat, gate the feature in your app with the RBAC ∩ entitlement rule: the membership must both hold the permission and have an active entitlement for an edition that unlocks the feature. See Authorization & feature gating for the claims and the authoritative runtime check.

Device trust

Activate devices against entitlements

Device activation binds hardware identity, application installation, licensing entitlement, and optional offline lease state. It is current GA for the documented activation lifecycle, while zero-touch IoT bootstrap remains preview.

Activation

Create, approve, heartbeat, renew, transfer, revoke

Start with POST /api/devices/activations using hardware fingerprint, display name, installation public key, application version, and entitlement ID.

Activation may become PendingApproval when the edition requires approval.
Offline lease issuance depends on the edition offline policy.
For device-aware OAuth tokens — device claims, trust gating, and continuous evaluation — see Device-bound, proof-of-possession tokens.

Device-bound tokens

Device-bound, proof-of-possession tokens

A device can prove possession of its credential at the token endpoint. When it does, the issued access token becomes device-aware — it carries device claims and is gated by the device-trust policy. The principal is user ⊕ device. A token request that presents no device proof and no client certificate is an ordinary token request and is left untouched.

Mechanism A

Signed-request proof (form parameters)

Send the net-new device_* form fields at /connect/token. The signature covers a canonical request over { grant_type, client_id, installation_id, application_version } bound to a one-time nonce and timestamp, reusing the platform's signed-request-proof scheme. No special deployment is required.

device_installation_id, device_application_version
device_proof_public_key, device_proof_signature
device_proof_nonce, device_proof_timestamp
device_proof_certificate_thumbprint (optional)

Mechanism B

mTLS client certificate

Present a client certificate on the connection. The device is resolved from the certificate thumbprint matching a registered X509Thumbprint device credential — no request parameters are sent. This is the natural bridge to a sender-constrained (mTLS-bound) token.

Either mechanism is accepted; neither is privileged.
Proof verification is the same security-critical check used by the device activation and lifecycle paths.

HTTP — device-aware token request (signed-request proof)

POST /connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=tenant-app&code=...&code_verifier=...
&device_installation_id=2f1c...e9
&device_application_version=1.4.0
&device_proof_public_key=<base64url SPKI>
&device_proof_nonce=<one-time nonce>
&device_proof_timestamp=<unix seconds>
&device_proof_signature=<signature over the canonical request>

Issuance is gated, with distinct denial reasons.

The gate applies to every device-proven token request regardless of grant type. An invalid or unverifiable proof is denied invalid_device_proof; a policy Block decision is denied device_blocked; a step-up decision is denied device_step_up_required. A pure client_credentials device token is still gated but does not yet carry device claims (no subject is present) — the resource-access guard re-evaluates live device state regardless.

Device claims

Claims embedded on a device-aware token

For subject-bound flows, the access token carries the device context below. These claims are informational for the client — they are not the authoritative gate. The authoritative decisions are the issuance gate (above) and the resource-access guard (below).

Claim	Meaning
`device_id`	Stable identifier of the proven device.
`installation_id`	The application installation the device proved possession for.
`device_risk_state`	Live risk classification of the device at issuance.
`device_trust_level`	Computed trust level. Attestation-weighted — a hardware-attested device resolves to `Trusted`.
`device_posture_version`	Optional. Version hash of the latest posture snapshot, when one is present.

Continuous evaluation

Re-check device trust at resource access

Device trust at issuance is a point-in-time decision. Opt a resource endpoint into Continuous Access Evaluation so it re-evaluates the device's live lifecycle, risk, and posture on every request — a device revoked or flagged after the token was issued is caught without waiting for the token to expire.

C# — opt a resource endpoint into the guard

// Re-evaluates the token's device_id / installation_id against live state.
app.MapGet("/reports/{id}", GetReport)
   .RequireDeviceTrust();

// Outcomes: Allow (proceed); Block (403); StepUp (403 "device_step_up_required");
// NoDeviceContext (token carries no device claims — left to your own policy).

Bind the token to the device so it cannot be replayed.

A device-aware token is still a bearer token until it is sender-constrained. The signed-proof path yields a DPoP binding (cnf.jkt, derived from the device proof key) and the mTLS path yields an mTLS binding (cnf.x5t#S256). The resource enforcement point checks the presented proof or client certificate against the token's cnf alongside the trust re-evaluation.

Near-real-time signals for external resource servers.

Beyond per-request re-evaluation, NexinID is an OpenID Shared Signals (CAEP) transmitter. A resource server can subscribe a push stream and receive signed Security Event Tokens — session-revoked, device-compliance-change, credential-change — when device trust changes. Discover the transmitter at /.well-known/ssf-configuration and verify the events against its published JWKS. Streams are managed through the transmitter's stream-management API and delivered over RFC 8935 push.

Application environments

Separate development, staging, and production per application

Each application can own named environments (for example development, staging, production) so configuration and clients are scoped per environment rather than mixed together. The number of environments an application may create is governed by your plan's MaxEnvironments quota.

HTTP — manage environments for an application

GET    /api/applications/{applicationId}/environments
POST   /api/applications/{applicationId}/environments
GET    /api/applications/{applicationId}/environments/{environmentId}
PUT    /api/applications/{applicationId}/environments/{environmentId}
DELETE /api/applications/{applicationId}/environments/{environmentId}

Quota-aware, and governed by application-management access.

Creating an environment is gated by the plan quota — the Developer tier includes a single environment and higher tiers raise the limit (see pricing). The same application-management permission that governs application edits governs environment changes.

Feature gating

Authorization and entitlement model

A feature is gated by two independent questions. RBAC answers whether the membership may perform an action; licensing answers whether the membership is licensed for it. A feature is available only when both are true — the rule is RBAC ∩ entitlement.

RBAC — "may"

Permission via roles, security groups, or direct grants

The membership holds the permission (featureKey, actionKey) through a role, a security group, or a direct grant. This is the existing application-authorization model and is validated against the application's active feature manifest.

Effective permissions are the union of role, group, and direct grants.
Resource-scoped policies can narrow a decision to a specific resource.

Licensing — "is licensed"

An active entitlement for an edition that unlocks the feature

The membership holds an active seat entitlement for a marketplace edition whose feature set includes featureKey. Each edition declares the manifest feature keys it unlocks, so licensing and the feature manifest share one canonical mapping.

The runtime resolves edition → feature set internally; callers gate on a feature key, not an entitlement id.
The legacy form that gates on a specific entitlementId remains supported.

Cache signals

Token claims for cache invalidation

Access tokens stay small: they do not carry per-feature or per-seat entitlement detail. Instead they carry version claims a client uses to know when a cached snapshot is stale, plus one optional coarse hint.

Claim	Scope	Use
`perm_ver`	`tenant_context`	Permission version. Bumps on any role, group, grant, or policy change. Re-fetch the cached authorization snapshot when it changes.
`ent_ver`	`tenant_context`	Entitlement version, symmetric with `perm_ver`. Bumps when the membership's entitlements or seat assignments change. Re-fetch the cached entitlement snapshot when it changes.
`entitled_editions`	Opt-in scope	Optional, default-off coarse list of edition codes the membership currently holds a seat for. Emitted only when the client requests its dedicated scope. A zero round-trip hint that may be up to one token lifetime (~1h) stale.

The coarse claim is a hint, never the gate.

Treat entitled_editions only as a fast-path optimization for non-sensitive UI (for example, deciding whether to render a menu item). Because it can be up to a token lifetime stale, a revoked seat may still appear present. Always make the authoritative decision with the runtime check below before allowing a sensitive operation.

Authoritative check

Gate a feature at runtime

The runtime is the source of truth. Call the scoped check with a licensed-feature key and the server evaluates RBAC ∩ entitlement in one request, resolving the edition → feature predicate for you.

HTTP — runtime feature check

POST /api/runtime/authorization/check-scoped
Authorization: Bearer <access token with tenant_context>

{
  "permissions": [ { "featureKey": "reports.advanced", "actionKey": "view" } ],
  "licensedFeatureKey": "reports.advanced"
}

Response

{
  "grantedAny": true,            // RBAC: the membership may
  "licensedFeatureKey": "reports.advanced",
  "featureLicenseSatisfied": true // Licensing: the membership is licensed
}
// Feature is available only when grantedAny AND featureLicenseSatisfied are both true.

C# — Nexin.SharedAuth SDK

// INexRuntimeAuthorizationClient wraps the runtime endpoints with
// perm_ver/ent_ver caching and a conservative deny when offline.

// One call returns RBAC ∩ entitlement (the authoritative gate):
bool canUse = await authClient.IsFeatureAvailableAsync(
    featureKey: "reports.advanced",
    actionKey: "view");

if (!canUse)
    return Forbid();

// Optional zero round-trip hint for non-sensitive UI only — never the gate:
if (authClient.IsEntitledToEdition("reports-pro"))
    ShowUpsellFreeMenuItem();

Use the scoped check when access depends on a resource or seat.

The runtime supports resource context alongside the licensing gate. Pass a resource scope to IsFeatureAvailableAsync (or check-scoped) when a decision is per-resource. Broader resource-policy authoring is still a guided rollout, not a universal self-service promise.

Operations

Audit webhooks and SIEM exports

Tenant-admin flows include webhook subscription management, one-time secret rotation, delivery status history, failed-delivery replay, CSV export, and NDJSON export.

Operational evidence stays tenant-aware.

Audit coverage spans identity, tenancy, applications, authorization, licensing, device trust, and platform operations, with delivery behavior documented for diligence review.

Analytics

Privacy-preserving analytics

Current analytics positioning is limited to organization-scoped aggregate authentication, audit, and device-fleet summaries with intentional suppression below the minimum cohort size.

No raw telemetry export claim.

The portal does not expose user-level risk scores or raw telemetry exports. Differential privacy remains a bounded pilot path, while federated or learned risk models remain roadmap scope unless explicitly agreed.

Security and trust

Diligence material that stays public-safe

The docs summarize the implemented platform without linking readers to private engineering notes. Use them for deployment posture, key handling, tenant isolation, audit visibility, and production-readiness expectations.

Logical tenant isolation inside one deployed instance.

Durable signing and data-protection material for production deployments.

Audit coverage across identity, tenancy, applications, authorization, licensing, device trust, and platform operations.

Dedicated tenant deployments, region pinning, and customer-managed key commitments remain guided commercial review unless contracted.