Permiso Docs

A user can’t sign in

Almost every case comes down to the same thing: the passkey is gone. A new laptop, a wiped phone, a browser profile someone deleted. The passkey lived on that device and didn’t come with them.

There are two ways back in. The user can recover on their own, or you can issue them a login code. Both end in the same place: a temporary code that gets them signed in once, after which they register a new passkey.

Let the user recover on their own

Point them at the login page and tell them to choose Alternative Sign In Methods, then Email Login. They enter their email address and get a code back by email, which they type into the next screen.

A few things to warn them about, because each one generates a follow-up question:

  • The code expires after 15 minutes.
  • They have to finish in the same browser they started in. The code is tied to that browser, so forwarding the email to their phone and entering the code there won’t work.
  • They can request three codes per 10 minutes. After that they’ll need to wait.

This route only works if the account has an email address on it, and if self-service recovery is switched on for your instance. If Email Login isn’t offered, it’s been disabled in Settings → Administration → Application Configuration.

Issue a login code yourself

Go to Settings → Administration → Users, find the person in the list, and choose Login Code from their row actions. Pick how long the code should last, from one hour up to a month, then either:

  • Send Email to have Permiso email it to them, or
  • Show Code to get the code on screen, along with a QR code and a link you can copy.

Codes you generate this way are not tied to a browser, unlike self-service ones. Create one on your own machine, read it out over a call or send the link, and the user enters it on their new laptop under Alternative Sign In Methods → Login Code. Use this when someone has no working email access, or when you’re setting someone up in person.

If Send Email isn’t offered, admin-issued email codes are switched off in Settings → Administration → Application Configuration. Use Show Code instead. The same applies if the account has no email address on it.

Pick the shortest expiry that works. A one-month code is a working credential for that account until someone uses it.

Then get a new passkey registered

The code signs them in once. It doesn’t leave a lasting way to log in, so if they close the tab without registering a passkey, you’ll be doing this again tomorrow.

Have them go straight to Settings → Account → Security and click Add Passkey on their current device. While they’re there, it’s worth removing the old one that no longer exists, so their credential list reflects reality. You can also delete stale passkeys from their profile page under Settings → Administration → Users.

To stop this happening again, see Set up a backup passkey.

When it isn’t the passkey

If recovery isn’t working, check these before digging further:

The account is disabled. A disabled user can get through the code step but is blocked the moment they try to do anything. The users list shows an Enabled or Disabled badge against every account, and re-enabling takes effect immediately.

They’re typing the code into the wrong browser. By far the most common failure with self-service recovery. See above.

Their account came from your directory. If the account is synced over LDAP or SCIM, changes made in Permiso can be overwritten by the next sync. Check whether the account was suspended upstream.

The app is rejecting them, not Permiso. If they sign in to Permiso fine but a specific application turns them away, it’s group access rather than authentication. See Groups.