Authentication

Every request carries an API key, and the key is the only credential. It also identifies the workspace, so you never pass a workspace id, and a key issued in one workspace can never read or write another.

What a key looks like

url_live_9fK3mQ2xR7vB4nL8pT1wY6zC0aE5sD3gH4jK7mN2

The url_live_ prefix is deliberate. It makes a key recognisable in a log or a pasted snippet, and it is the pattern secret scanners look for, which is what stops a key committed by accident from sitting unnoticed in a repository.

Sending a key

Authorization: Bearer url_live_YOUR_KEY

Nothing else is required. If you would like to check a key before wiring it into anything, the cheapest possible call is a one-link listing:

curl -X GET "https://urlicer.com/api/v1/links?size=1" \
  -H "Authorization: Bearer url_live_YOUR_KEY"

A working key answers 200. A missing, mistyped, revoked or expired key, and a key belonging to a workspace that has been deactivated, all answer the same thing:

{"error": "unauthorized"}

The response is deliberately identical in every one of those cases. Telling you which way a key failed would also tell someone guessing at keys when they had found a real one.

Creating and revoking

Keys are managed in the dashboard, under API keys in your workspace. The API has no endpoints for keys, so a leaked key cannot be used to create a replacement for itself before you revoke it.

• Only Owners and Admins of a workspace can create or revoke keys, and only after confirming their email address.
• The key is shown once, on the screen that creates it. We keep only a hash, so it cannot be shown again. Lost it? Revoke it and create another.
• Revoking takes effect immediately. Any request that arrives after you revoke the key answers 401. A request that had already passed authentication when you revoked it still completes.
• A key can be given an expiry when you create it. Set one for anything temporary, such as a contractor's integration or a one-off migration.

Rotating without downtime

Because a key can be revoked instantly and a workspace can hold several at once, rotation does not need a maintenance window:

1. Create a second key, named for the rotation, like "api key 2026-08".
2. Deploy it. Both keys work, so a rolling deployment is fine and a rollback is safe.
3. Wait until the old key stops being used. The keys page shows when each key was last used, but read the note below before relying on it.
4. Revoke the old key.

How "last used" is recorded. Writing it on every request would put a database write in front of every API call. So we record a key's very first request straight away, and after that only every 100th request. The time shown can be up to 99 requests out of date, and because this counts requests rather than time, a key that makes a few calls a week can keep showing a date from weeks ago while it is still in use. Before revoking an old key, check your own logs or deployments as well.

Looking after a key

Keep a key as secret as a password. Anyone holding it can create, re-point and delete links in your workspace, and some of those links may already be printed.

• Keep it in whatever secret store your deployment already uses. Not in source control, and not in a config file that ships alongside the code.
• Never put a key in anything that reaches a browser, such as front-end JavaScript or a mobile app bundle. Anything shipped to a device can be read on that device. Call your own backend, and let it hold the key.
• Use a separate key for each system that calls us. Revoking one integration then does not take down the others, and each key gets its own request budget.
• Every write a key makes is recorded in the workspace audit trail against the key name, since no person was at a keyboard. Name keys after where they run so the trail is easy to read.

How many keys you can hold

Plans cap how many live keys a workspace may hold at once: 1 on Free, 3 on Pro, 10 on Team and 25 on Business. The rate limits page reads the current numbers from our plans. Revoked and expired keys stay in the list as history but do not count against the cap. The cap exists because the request budget is measured per key: see rate limits.