Authentication
One bearer key per workspace. Create it, send it, rotate it, revoke it.
Every request carries an API key. There is no session to establish, no token to exchange and no workspace id to pass. The key identifies the workspace, so a key issued in one workspace can never read or write another.
What a key looks like
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
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, not through the API, because a key that can mint keys is a key that can never really be revoked.
- 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. The next request made with that key fails, including one already in flight from a server you have forgotten about.
- A key can be given an expiry when you create it, which is worth doing for anything temporary: a contractor integration, a one-off migration, a trial.
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:
- Create a second key, named for the rotation, like "api key 2026-08".
- Deploy it. Both keys work, so a rolling deployment is fine and a rollback is safe.
- Wait until the old key stops being used. The keys page shows when each key was last used, which is the signal to look for.
- Revoke the old key.
"Last used" lags on purpose. Recording it on every request would put a write in front of every API call, so we record it periodically instead. A key you started using a minute ago may still read "Never". Give it a few minutes before concluding that nothing is using a key you are about to revoke.
Looking after a key
Treat a key exactly as you would a password, because that is what it is: anyone holding it can create, re-point and delete links in your workspace, and those links are already printed on things.
- 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. Front-end JavaScript, a mobile app bundle, a public repository. 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 per system that calls us. It costs nothing, "last used" then tells you something specific, and revoking one integration does not take down the others.
- Every write a key makes is recorded in the workspace audit trail against the key name, since no person was at a keyboard. Another reason to name keys after where they run.
How many keys you can hold
Plans cap how many live keys a workspace may hold at once: one on Free, more on each paid tier. 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.