Password-protected links

Prerequisites

• A workspace plan that includes password-protected links (currently Pro and above).
• Workspace Admin or Member role.
• When using the API: a valid workspace API key for link-management calls, and a secure server-side environment (never pass passwords from a browser).

---

How password protection works

Password protection inserts a secure server-side gate before the redirect. Here is the complete visitor flow:

1. A visitor clicks your short link.
2. Nimriz checks whether the link has a password. If it does and the visitor has no valid unlock cookie, instead of redirecting immediately, Nimriz serves a small password entry form.
3. The visitor types the password and submits the form.
4. Nimriz verifies the submitted password against a stored hash on its servers. Passwords are never stored as plaintext and are never returned in API responses or the dashboard.
5. If the password is correct, Nimriz issues a signed, link-specific session cookie and redirects the visitor to the destination.
6. On all subsequent visits from the same browser, Nimriz finds the valid cookie and redirects immediately without showing the password prompt again.

Cookie scope: The unlock cookie is scoped to the exact link (url_id), domain, and short code. Unlocking one password-protected link on a domain does not unlock any other protected link on that domain. Each protected link requires its own unlock.

---

Link states

A password-protected link is always in one of three states from the visitor's perspective:

State transitions:

• Adding a password: unprotected → protected_locked
• Correct password entry: protected_locked → protected_unlocked
• Removing a password: protected_locked / protected_unlocked → unprotected
• Invalid or tampered cookie: treated as protected_locked (prompt shown again)

---

Adding password protection in the dashboard

When creating a new link:

1. Open the link creation modal.
2. Expand the Security or Advanced section.
3. Enable the Password protection toggle.
4. Enter the password you want visitors to provide.
5. Complete link creation.

On an existing link:

1. Open the link detail page for the link you want to protect.
2. Find the Password section in the link settings.
3. Enter a password and click Save.

The password takes effect immediately.

---

Managing passwords via the API

Set or update a password

PUT https://api.nimriz.com/api/update-password
Authorization: Bearer <WORKSPACE_API_KEY>
Content-Type: application/json

{
  "url_id": "22222222-2222-2222-2222-222222222222",
  "password": "my-secure-password"
}

Successful response:

{
  "url_id": "22222222-2222-2222-2222-222222222222",
  "password_protected": true
}

Remove a password

PUT https://api.nimriz.com/api/update-password
Authorization: Bearer <WORKSPACE_API_KEY>
Content-Type: application/json

{
  "url_id": "22222222-2222-2222-2222-222222222222",
  "password": null
}

Passing null as the password removes protection entirely. The link reverts to immediate redirect behavior.

Create a link with password protection

Include the optional password field in a POST /api/shorten request:

{
  "domain_id": "00000000-0000-0000-0000-000000000000",
  "long_url": "https://example.com/secure-resource",
  "custom_slug": "internal-launch",
  "password": "launch-2026"
}

---

Security details

• No plaintext storage: Passwords are hashed on the server before being stored. The original plaintext is discarded immediately.
• No plaintext exposure: The API never returns a link's password-even to workspace admins. If a password is forgotten, the only option is to set a new one.
• Cookie tamper protection: Unlock cookies are cryptographically signed. A cookie from one link cannot be used to unlock a different link.
• Server-side only: Always set and update passwords from a trusted backend. Never pass password values through browser-side code or expose them in front-end environment variables.

---

What happens when you change a password

When you update a link's password, the new password takes effect immediately. Visitors who previously had a valid unlock cookie for the old password will see the password prompt again on their next visit, because their old cookie is no longer valid.

This means: communicate password changes to your intended audience if you are rotating passwords on an actively shared link.

---

Troubleshooting

The password prompt keeps reappearing for a visitor

Check these in order:

1. Wrong password entered-the visitor may be mistyping the password. Confirm they are using the current password (not one from before a recent update).
2. Password was recently changed-existing cookies from the old password are invalidated. The visitor must enter the new password once.
3. Browser cookies are blocked-the unlock mechanism requires cookies. If the visitor's browser is blocking third-party cookies or has a strict privacy setting, the cookie may not be saved. Ask the visitor to check their browser cookie settings.
4. Private/Incognito mode-cookies do not persist across incognito sessions in most browsers. The visitor will need to re-enter the password each time they open a new private window.
5. Visiting a different link-each protected link requires its own separate unlock. If the visitor bookmarked a different link on the same domain, it has its own independent cookie.

The password protection option is not visible in the dashboard

Password protection is plan-gated. If the option is not showing in your link creation or link settings UI:

• Confirm your workspace is on a plan that includes this feature.
• Contact your organization administrator to check your current plan and any workspace-level feature settings.

The API returns feature_not_enabled when setting a password

Your workspace plan does not include password-protected links. Upgrade your plan or contact support to enable this capability for your account.

A redirect works in one browser but prompts for a password in another

This is expected behavior. The unlock cookie is stored per-browser and per-device. A visitor who unlocked the link on their laptop will need to enter the password again on their phone or a different browser-the cookie does not sync across devices.

---

Related guides

• Link creation and slugs
• API reference
• Integration patterns