// help center

Start with the path you need.

Secure one account, operate the realm you are responsible for, or connect an application to Neima ID. Each path points only to behavior available in the current control plane.

Choose a path

Neima ID separates personal account tasks, realm operations, and application integration. Choose the role that matches what you need to accomplish now.

accountSecure your accountSign in, add a passkey and second factor, and review your active sessions.Follow this path realm adminAdminister a realmBootstrap the first realm, invite people, register apps, and inspect audit activity.Follow this path integratorIntegrate an applicationRegister exact callbacks and implement Authorization Code with PKCE.Follow this path

Secure your account

Enrollment is invitation-only. A realm administrator sends a link bound to your verified email address and realm host. New accounts choose a password of at least 12 characters, then use the portal to add stronger sign-in methods and review activity.

1Open your realm invitationReview the enrollment overview at invitation required, then open the single-use link sent by your realm administrator. The link must match the invitation's realm host before Neima ID creates an account or membership. Existing users sign in before accepting it.
2Add a phishing-resistant passkeyIn Security, register a platform authenticator or hardware key. Passkeys are the recommended primary sign-in method.
3Add TOTP as a second factorScan the enrollment QR code with an authenticator and store the recovery material safely. TOTP strengthens a primary sign-in; it is not a separate first-step login method.
4Review sessions and devicesUse Sessions to inspect active sessions and revoke anything you do not recognize.

Passkeyrecommended

Primary sign-in using Face ID, Touch ID, a device PIN, or a hardware security key.

Passwordprimary

Primary sign-in with the configured minimum and reset-email recovery.

Magic linkprimary

Primary email-based sign-in when outbound auth email is configured.

PGP challengeadvanced

Primary proof for accounts that have already registered a PGP public key.

TOTPsecond factor

Time-based codes used after a primary method when stronger assurance is required.

Session controlsaccount

Inspect and revoke active sessions from the portal without changing another device directly.

Your OIDC subject (sub) is an opaque, stable identifier. Current subject IDs are UUIDv7 values. Never infer time, tenant, role, or user meaning from their format, and never rely on a prefix.

Open account portal

Administer a realm

The request host selects the realm, then stored membership authorizes the user. Membership roles are member, realm_admin, and super_admin. The admin console accepts realm administrators and super administrators; ordinary members remain in the portal.

The first neima realm and owner are bootstrap-seeded. Realm settings are currently read-only, and this release does not include a realm-creation UI. Use the reviewed operator workflow in docs/GETTING_STARTED.md instead of editing production data by hand.

Register an applicationCreate the directory app and its OIDC client together; record the client secret when it is revealed.Invite a personSend an invite, then assign only the groups and app roles the person needs.Issue a management tokenChoose the smallest scopes, set an expiry, and copy the realm-bound token once.Add a webhookChoose event filters, store the endpoint secret once, and send a test event before relying on delivery.Review the audit trailUse realm-bound events to investigate privileged changes and security-sensitive activity.

Applications, people, groups, grants, API tokens, webhooks, licensing, flags, policies, and audit events are realm-scoped. A missing realm or membership must fail closed; a super_admin override is explicit stored membership rather than an email-domain shortcut.

Open admin console

Integrate an application

Register the application in the correct realm, use an exact redirect URI, and implement OpenID Connect Authorization Code with S256 PKCE. Dynamic client registration is disabled.

1Register the clientChoose confidential web or public native, enter every exact callback and post-logout URI, and store a confidential client secret only on the server. Native clients do not receive a usable secret.
2Discover provider metadataRead https://id.neima.me/.well-known/openid-configuration. The issuer is https://id.neima.me/api/auth; validate it exactly instead of constructing endpoints yourself.
3Keep the transaction server-sideGenerate state, nonce, and a PKCE verifier for every attempt. Keep them in an encrypted, short-lived, single-use transaction owned by your application.
4Validate the callbackMatch the callback URI and state, exchange the code with the verifier, then validate signature, issuer, audience, expiry, and nonce. Require the UserInfo subject to match the ID token subject.
5Create your application sessionStore only the identity and authorization state your app needs, set secure cookie attributes, and define logout and refresh behavior in the relying application.

@neima/id is a private, repository-local package. There is no supported public registry or CLI install. Consumers either vendor an exact reviewed SDK snapshot through a file: dependency or use a maintained standards-compliant OIDC library. Application session and cookie adapters remain application-owned.

Neima ID claims used by relying applications
Claim	Meaning	Rule
sub	Opaque account subject	Key records by it; never parse it
nid:roles	App roles	Authorize by exact role keys
nid:features	Enabled feature keys	Treat absence as disabled
nid:lic	Resolved license summary	Treat null as no license
nid:authz_v	Authorization version	Use for cache invalidation
nid:auth_level	pwd, mfa, or passkey	Require the level the action needs

Management API

Realm-bound bearer tokens use explicit read/write scopes. Inspect the live contract at /api/v1/openapi.json.

Webhooks

Verify the raw body against the neima-signature header, enforce timestamp tolerance, and reject replays before processing.

Security model

Fail closed

Suspended realms, missing memberships, invalid OIDC transactions, and unverified webhook signatures are denied.

Short-lived proof

Authorization codes and tokens expire. State, nonce, PKCE, session revocation, and step-up checks limit replay and privilege reuse.

Least privilege

Realm membership opens the correct plane; app grants, token scopes, license state, flags, and policies narrow what a caller may do.

Operational evidence

Privileged mutations write audit events. Health confirms service reachability, while real sign-in and integration checks prove the workflow itself.

Check current process health at /api/health. A healthy response does not by itself prove email delivery, webhook dispatch, an external relying party, or every configured integration.

Report a suspected account or integration issue to security@neima.me. Do not include passwords, tokens, recovery material, private keys, or production secrets.

FAQ

Is TOTP a standalone sign-in method?

No. TOTP is a second factor used after a primary method such as a password. A passkey can provide strong primary authentication without a separate TOTP prompt when policy allows it.

What if I lose a device?

Use another enrolled method, then revoke the missing device's session and credential from the portal. If no method remains, use the supported recovery flow and contact an administrator without sharing secrets.

Why can I sign in but not open an app or the admin console?

Authentication and authorization are separate. Confirm the request host resolves to an active realm, your account has membership in it, and the required app grant or realm-admin role is present.

Can I install the SDK from a public registry?

No. The current SDK is private and repository-local. Use an exact reviewed vendored snapshot through a file dependency, or integrate with a maintained OIDC library using discovery metadata.

Why are webhooks queued but not arriving?

Confirm the endpoint is active, its event filters match, and the dispatch loop is enabled. Then inspect delivery attempts; never disable signature or timestamp verification to make a test pass.

Operators and integrators should continue with the repository's docs/GETTING_STARTED.md and docs/integrations/README.md. Those guides include local setup, testing, deployment, recovery, and protocol-specific next steps.