API authentication

Generate, send, rotate, and revoke workspace API keys and partner install tokens for secure server-side API access.

Overview

This page covers how to authenticate with the Nimriz API: the key types Nimriz supports, where to generate them, how to send them, and how to keep them safe. For the broader auth model covering dashboard login, SSO, and session behavior, see Auth model.

Nimriz issues API credentials at the workspace level. Every key is tied to exactly one workspace, and it cannot reach data or settings in any other workspace.

Key types

Type	Where you get it	What it can do
Workspace API key	IntegrationsDeveloperBackend API access in the dashboard	Call selected API route families for one workspace, limited by explicit scopes, resources, status, and expiration.
OAuth grant	Sign in with Nimriz from a supported platform or MCP client	Delegate selected workspace scopes to that client. Revoking the grant disconnects the client.
Partner install token	Issued for platform connections (Zapier, Make, n8n)	Drive the workspace endpoints the connected platform uses, nothing else. Install tokens appear in the same principal list as workspace keys.
Organization admin key	SettingsOrganizationGovernance in the dashboard	Manage organization-plane API principal governance only. It cannot read or mutate workspace links, analytics, domains, webhooks, conversions, or integrations.

Keys are service credentials. They belong to the workspace, not to the user who created them. When an admin leaves, their keys keep working until another admin revokes them.

Sending a key

Every key-authenticated API call accepts the key in one of these headers:

Authorization: Bearer <WORKSPACE_API_KEY>

X-Nim-Api-Key: <WORKSPACE_API_KEY>

Use the Authorization: Bearer form by default; it is the most widely supported across HTTP clients and SDKs.

The MCP server accepts OAuth connections from clients that support Nimriz sign-in, plus workspace API keys for clients that send custom headers.

Managing keys

To generate a workspace API key:

Go to IntegrationsDeveloperBackend API access in the dashboard.
Enter a descriptive key name.
Select at least one scope and one resource.
Choose an expiration.
Click Generate key.
Copy the key from the one-time reveal. Nimriz does not store the plaintext; if you lose it you must rotate or generate a new key.

To rotate a key:

Open the same panel.
Use Rotate to replace the token value.
Copy the new key from the one-time reveal.

To extend a key:

Open the same panel.
Use Extend to set a new expiration.

To revoke a key:

Open the same panel.
Find the key and click Revoke. Revocation is immediate and permanent. Generate or rotate a key instead of reusing a revoked one.

Workspace admins can generate, rotate, extend, and revoke workspace API keys. Members and viewers can see the principal list in read-only mode, but they never see token prefix or last-four values.

Scopes and resources

Every workspace API key has a non-empty scope set. Wildcards are not supported. Common scopes include:

Scope	Allows
`links:read`	Read link records through supported API routes.
`links:write`	Create or update links through supported API routes.
`analytics:read`	Read supported analytics endpoints.
`webhooks:write`	Manage webhook endpoints.
`connections:write`	Manage integration destinations.

Every key also has an explicit resource allowlist:

Resource	Use
`https://api.nimriz.com`	REST API routes.
`https://api.nimriz.com/mcp`	MCP server access.

REST and MCP are separate resource audiences. A key valid for one resource is rejected on the other unless both are selected.

Organization governance

Organization owners and admins can use SettingsOrganizationGovernance to review principals across workspaces, filter by kind or status, revoke principals, create narrow organization admin keys, and provision a workspace-bound key into a selected workspace.

Organization admin keys are not cross-workspace data tokens. If automation needs workspace data, provision a separate workspace key for each workspace.

Connecting automation platforms

Zapier and n8n can connect to Nimriz through OAuth or through a workspace API key, depending on the platform connection screen you see.

If the platform shows Sign in with Nimriz, approve the requested workspace and scopes in Nimriz. Revoking the OAuth grant from the dashboard disconnects the platform.
If the platform asks for a key, generate a workspace API key from IntegrationsDeveloperBackend API access and paste it into the platform's connection dialog. Revoking that key disconnects the platform.

Existing API-key connections keep working. To reconnect with OAuth, create a new platform connection and select it in the automation.

Make remains invitation-based. Use the Make guide for the currently supported setup.

For platform-specific setup, see the Zapier, Make, and n8n guides.

Connecting MCP clients

MCP clients can use Nimriz OAuth when their connector setup offers Nimriz sign-in. The OAuth token is scoped to the MCP resource https://api.nimriz.com/mcp and cannot be used on REST API routes.

Clients that can send custom headers can use a workspace API key with Authorization: Bearer <WORKSPACE_API_KEY>. URL-only clients can use the MCP connector URL described in MCP server.

Security rules

Store keys in server-side environment variables only. Never embed a key in a browser bundle, a mobile app, a client-side script, or a public repository.
If you suspect compromise, revoke the key immediately from the Backend API access panel and generate a replacement.
Use a dedicated key per integration or environment (staging, production) so you can revoke one without disrupting the others.
Monitor your workspace's audit log for unexpected link creations or destination changes.

Common errors

Response	Meaning
`401 Unauthorized`	Missing or malformed `Authorization` header. Check the header name and that the key starts with the correct prefix.
`401 invalid_api_key`	The key is not recognized. It may have been revoked, or the value may have been truncated or mistyped.
`401 token_expired`	The key has passed its expiration. Rotate or extend it from the dashboard.
`403 api_key_account_mismatch`	The key is valid but belongs to a different workspace than the resource you are addressing. Use a key from the correct workspace.
`403 resource_audience_mismatch`	The key is not allowed for the REST or MCP resource you called.
`403 scope_required`	The key is missing the required scope for that operation.

Related guides

Related next steps

Nimriz documentation

Follow setup and reference guides for Nimriz products and integrations.

Features

Explore Nimriz branded link, QR, analytics, routing, and team capabilities.

Ready to test this setup?

Create an account to try the workflow, or compare plans when the setup needs higher limits, integrations, or team controls.

Start for free Compare plans