Authentication model

Overview

The Nimriz auth model separates two concerns:

1. Authentication-proving who you are (logging in).
2. Authorization-determining what you can access (workspace membership and roles).

A successful login does not automatically grant access to any workspace. A user must also have a workspace membership (via invitation) before they can view or operate on workspace data.

---

Key principles

One canonical profile per person. Whether you log in with a password, Google, Microsoft, or SAML, all authentication methods map to a single stable Nimriz profile for your email address. Switching from password login to Google SSO does not create a duplicate account-it links the new method to your existing profile.

Server-side API calls only. Never call Nimriz link-management or control-plane APIs from the browser or from mobile apps. Your workspace API key and conversion signing secret must live only in your backend server environment.

Workspace scoping. API keys and conversion secrets are scoped to a specific workspace. An API key from workspace A cannot create links or access data in workspace B.

Organization-plane keys are separate. Organization admin keys can manage organization-level API principal governance, but they cannot access workspace links, analytics, domains, webhooks, conversions, or integrations.

---

Supported authentication methods

---

Organization and workspace scope

Nimriz uses a two-level structure:

Organization (billing, governance, domain ownership)
  └── Workspace (links, API keys, team members)
        └── Users (workspace roles: admin, member, viewer)

• Sessions carry both an active organization and an active workspace context.
• API keys are workspace-scoped-they can only perform operations within the workspace they were generated in.
• SSO and governance settings (like enforcing SSO for all members) are configured at the organization level.
• 2FA enforcement can be set at the workspace level by workspace admins.

---

Workspace API keys

Workspace API keys are used for supported link-management operations: creating links (including bulk creation), checking slug availability, updating slugs, setting expirations, and updating link passwords. Routing rules are managed from the dashboard, not through workspace API keys. The Backend API access panel lists the currently supported routes.

Generating a key:

1. Go to Integrations›Developer›Backend API access.
2. Enter a key name.
3. Select scopes, resources, and an expiration.
4. Click Generate key.
5. Copy and securely store the key. It is shown only once.

Using a key:

Authorization: Bearer <WORKSPACE_API_KEY>

Or:

X-Nim-Api-Key: <WORKSPACE_API_KEY>

Security rules:

• Store API keys in server-side environment variables only.
• Never include API keys in front-end code, browser extensions, or client-side configuration.
• Never commit API keys to version control.
• Rotate keys immediately if you suspect compromise. Old keys can be revoked from the Integrations settings.
• Every key has explicit scopes and resource audiences. Wildcard scope sets are not supported.
• Workspace members and viewers can see principal status in read-only mode, but token prefix and last-four values stay hidden.

Organization API governance

Organization owners and admins can manage API principals from Settings›Organization›Governance.

They can:

• Filter principals across the organization.
• Revoke workspace keys, partner installs, OAuth grants, and org keys.
• Create narrow organization admin keys for org-plane automation.
• Provision a separate workspace key into a selected workspace.
• Set policy for active principal counts and expiration.

Organization admin keys use organization-plane scopes such as org_api_keys:read, org_api_keys:revoke, and workspaces:read. They are not accepted on workspace data routes.

---

Conversion API signing secret

The Conversion API uses a separate workspace-level signing secret-not the workspace API key.

Why they are separate: The Conversion API is for recording post-click business outcomes (sales, leads, refunds) from your backend. Keeping it separate allows you to rotate credentials independently, and it makes the intended use case clear-conversion events do not use general link-management auth.

Generating a conversion secret:

1. Go to Integrations›Developer›Conversion API.
2. Click Generate Conversion API secret. (Once one exists, the same button reads Rotate Conversion API secret and immediately replaces the previous secret.)

Using the secret: See Conversion tracking for the full signing flow.

---

Enterprise SSO (SAML)

Enterprise SSO is configured at the organization level by an Org Owner or Org Admin.

How SSO routing works

When a user signs in, Nimriz checks their email address against the organization's configured SSO email domains. If the email matches a registered SSO domain, the user is routed through that organization's SAML provider.

SSO email domains are separate from your Nimriz short-link domains. A domain used for short links (e.g., links.example.com) is different from the SSO email domain (e.g., example.com) used to route login traffic.

Linking SSO to an existing account

When an existing password or Google user logs in via SAML for the first time, their SAML identity is linked to their existing profile-no duplicate account is created. The user continues to access the same workspaces they had before, now through SSO.

SSO enforcement

Org Owners can enforce that all organization members must log in via SSO. Enforcement requirements:

1. A SAML provider must be active and successfully tested.
2. SSO email domain routing must cover the intended user population.
3. A recovery path must be defined for the owner account (e.g., a linked Google identity or backup credentials).

When SSO is enforced:

• Members who do not have a compliant SSO login method are placed into a remediation flow on login.
• They must authenticate via the configured SSO provider before accessing any workspace content.

SSO does not automatically provision workspace access

A user who logs in via SSO for the first time but has no pending workspace invitation will be in an authenticated-but-no-access state. They will need to accept a workspace invitation before they can access workspace content.

---

Authorization behavior after login

After a user successfully authenticates:

1. Nimriz resolves their active organization and workspace from their session state.
2. Their workspace role (admin, member, viewer) is checked for each operation.
3. API requests from backend integrations use the workspace API key's permissions-there is no user-specific role associated with an API key.

Workspace API keys have the same link-management capability as a workspace Admin for link operations. They do not have access to user management, billing, or governance settings.

---

Troubleshooting

Logged in via SSO but cannot access the workspace

You have authenticated your identity but have not yet been added to a workspace. Contact your Org Admin to either send you a workspace invitation or add you to the relevant workspace directly.

SSO enforcement cannot be enabled

Confirm all prerequisites are met: a tested SAML provider is active, SSO email domains are configured and verified, and you have defined a recovery path for the owner account.

API calls return 401 even with a valid key

• Confirm the key is being sent in the correct header (Authorization: Bearer <key> or X-Nim-Api-Key: <key>).
• Confirm the key belongs to the workspace you are targeting. Keys are workspace-scoped and cannot access other workspaces.
• Confirm the key has not been revoked in your Integration settings.

API key was exposed

1. Go to Integrations›Developer›Backend API access immediately.
2. Revoke the compromised key.
3. Generate a new key.
4. Update your server environment variables with the new key.
5. Monitor your workspace's link activity for any unexpected creations.

---

Related guides

• Organizations and workspaces
• Two-factor authentication
• API reference
• Integration patterns