Sheet POR-09 · Identity Manual

Mobile Authenticator & Recovery

The Portal Authenticator app: one-time codes, linked devices, sign-in approval and backups.

Audience: Identity administrators and support staff Focus: Authenticator setup and recovery

Scope

How people set up the Portal Authenticator app on iOS or Android, link it to their Portal account, and use it to approve sign-ins and access requests.

What the app does

Portal Authenticator is a free app for iPhone and Android. It does three things:

Generates one-time codes for any account that uses an authenticator app, including accounts that have nothing to do with Portal. Codes are stored only on your phone.
Links to your Portal account so you can approve sign-ins and access requests from your phone, and on iPhone sign in to Portal without a password.
Backs up your codes (iPhone) to a personal, end-to-end encrypted vault that only your devices can read.

The Android app covers one-time codes, linking, and approving access requests. Sign-in approval, push notifications and the personal vault are iPhone features today.

Get one-time codes into the app

Tap + on the Authenticator screen.

You have	Do this
A setup QR code on a website	Scan QR Code and point the camera at it.
A setup key (text)	Enter Setup Key, then type or paste the issuer, account and key.
Google Authenticator on your old phone	In Google Authenticator choose Transfer accounts, then Export accounts. In Portal Authenticator choose Scan QR Code and scan each code it shows. The sheet says “Scanned 1 of N” until you have scanned them all; nothing is saved until the last one. Accounts you already have are skipped.
A screenshot or photo of a QR code	Scan QR Code, then Choose a Screenshot or Photo.
A setup link in your clipboard	Scan QR Code, then Paste Setup URL.
A Portal Authenticator encrypted file	Import & Export, then Open Encrypted File. Pick the file and enter its passphrase.

If a code cannot be imported, the message says why and offers Fix Manually, which opens the editor with everything it could read already filled in.

Take codes out

Tap +, then Import & Export:

Show QR Codes for Another App displays export codes that any authenticator able to import from Google Authenticator can scan (up to 10 accounts per code, with “1 of N” paging). These codes contain your secrets. Do not screenshot or share them.
Save Encrypted File asks for a passphrase of at least 8 characters, entered twice, and saves an encrypted file to Files. The passphrase is not stored anywhere. If you lose it, the file cannot be opened.

A single account’s setup QR code is on its detail screen under Show Setup QR Code.

Accounts that need repair

After restoring an iPhone from a backup, account details can come back without their secret keys, because secrets stay on the original device. Those accounts appear at the top under “N accounts need repair” with the reason. They are never deleted for you.

Repair opens the editor with the issuer and account filled in. Enter the secret key from the service or from your export and save.
Delete removes the entry after a confirmation.

Swipe a repair row right for Repair and left for Delete.

Organise the list

Swipe right on an account for Pin (keeps it at the top) or Edit. Swipe left for Delete. A long press shows the same actions.
Reorder at the top of the screen lets you drag accounts into your own order. Tap Done to finish. Until you reorder, accounts are alphabetical.
In the editor, Organize adds a group (for example Work or Personal), a Pin to top switch and an icon. Grouped accounts appear under their group heading, and search matches group names.
In the last few seconds before a code changes, the row shows Next with the upcoming code.

Copying and locking

Tapping a code copies it for 60 seconds on this phone only. It does not sync to another device’s clipboard.
When you save your first code the app offers, once, to turn on Face ID or Touch ID lock. Change it any time in Settings. With the lock on, switching away for under 30 seconds does not ask you to unlock again.

Back up your codes (iPhone)

Open Settings, then Vault Backup & Recovery. The vault is a personal account, separate from your work Portal account, so you can keep it when you change employers and delete it yourself at any time.

Sign up with your email and a passkey. No employer or Portal tenant is involved.
Save the recovery key. It is shown once, and you confirm that you saved it. It is the only way back in if every enrolled device is lost.
When the Authenticator tab shows Your codes aren’t backed up, tap it to encrypt and upload your entries.
To add a second device, open the vault on the new device to show a QR code, then scan and approve it from a device that is already enrolled.

Portal’s servers only ever hold encrypted data. They cannot read your codes or your vault key. Deleting the vault account is separate from unlinking the app from your work Portal account. Restoring synced codes onto a second device and Android support are future additions.

Link the app to your Portal account

Linking lets your phone approve actions and sign-ins. It is optional and can be undone at any time.

In a browser, sign in to Portal and open Profile, then Mobile Devices. Select Pair Mobile Device.
Portal shows a QR code, a Pairing ID and a Short code. They are valid for 5 minutes.
In the app, tap Link Device and scan the QR code, or enter the Pairing ID and Short code.
The browser page waits while your phone proves it holds its key, then shows Device paired successfully.
If the app is already signed in to Portal, it ties that sign-in to this phone. Nothing is shown unless that step fails; the app’s Portal readiness screen then reads “pending” and it retries automatically.

Rules that apply:

You can keep up to 5 active linked phones. Pairing a sixth fails with a message; revoke an unused phone under Profile, then Mobile Devices, and pair again. The pairing code stays valid for the rest of its 5 minutes, so you do not need to start over.
Re-pairing the same app installation (for example after a restore) replaces the old entry and does not count as a new phone.
After 5 wrong Short code entries the pairing is cancelled. Start a new one.
A phone that has not been used for 180 days is unlinked automatically. It stays listed as revoked so you can see what happened, and it must be paired again to be used.
Each pairing and each revoke is recorded in your tenant’s audit log, and a pairing can also trigger your organisation’s Webhooks subscriptions.

Verified devices

When it pairs, the app proves it is a genuine, unmodified Portal Authenticator running on a real device (Apple App Attest on iPhone; Google Play Integrity or Android key attestation on Android). Approvals from a phone that could not be verified are refused. If an approval says the device needs verification, revoke the phone in Portal and pair it again from the app.

Open the Devices tab and tap Sign In With Portal.
Portal’s normal sign-in opens in a secure browser sheet: password or passkey, second factor, tenant choice and consent, exactly as on the web.
Portal returns you to the app, which now shows your linked devices.

From the Devices tab you can see every linked phone for the tenant you chose and revoke any of them. Revoking a phone signs that phone out of Portal straight away; other phones are not affected.

If Portal signs this phone out (you or an administrator revoked it, it went dormant, or it was re-paired elsewhere), the Devices tab shows Portal Sign-In Required Again and explains why. To use the phone again, pair it again and sign in. A plainly expired sign-in keeps the link and only asks you to sign in again.

Use your own Portal (iPhone)

The app points at the Portal its build was made for. If your organisation runs its own Portal:

Sign out of Portal in the app. The address cannot change while a session is signed in.
Open Settings, then Portal Address.
Under Use A Self-Hosted Portal, enter the address you open Portal at in a browser, for example portal.example.com, with no scheme and no path.
Leave Portal API address blank unless your organisation told you it uses a separate API address.
Tap Verify And Use This Portal and confirm.

The app checks that the address is a working Portal before switching. Nothing is saved if the check fails. The common messages:

Message	What it means
Not a Portal deployment, or a typo	The host answered but is not a Portal. Check the address.
The host returned something this app cannot use	You may have entered the website address of a Portal that uses a separate API address.
Enter the named host as the Portal API address	The message tells you exactly which host to put into Portal API address.
Portal must be reached securely	The address must use a secure (TLS) connection.
Sign out of Portal before changing the address	Step 1 was skipped.

Switching clears this phone’s link with the previous Portal, so pair again on the new one. Your one-time codes are not affected. Portal Address always shows which Portal is active and whether it is built into the app or entered on this device. Use The Address This Build Ships With switches back.

Approve requests from your phone

Access-request approvals, access-review decisions and support-access decisions all use the same steps:

Open the request in the app and tap the action, for example Continue to Approve. The app asks Portal for a one-time challenge. Nothing is approved yet.
A number-match sheet shows a 3-digit code, what you are approving, and a countdown. Challenges expire after 5 minutes. Compare the code with the one Portal shows where you started the action: the browser prompt or the notification banner.
Tap Code matches to approve, deny, keep or revoke. Only now does your phone sign the decision with its own key and send it. Cancel discards the challenge.

The sheet refuses to continue if the prompt has expired, or if a notification for this challenge carried a different code. In that case cancel, start the action again from the request, and if you did not start it, deny it in Portal and review your linked devices.

A notification on its own can never approve or deny anything. Portal only accepts a decision signed by your linked phone after you compared the code.

Push notifications (iPhone)

Link the phone and sign in to Portal in the app. Nothing push-related happens before both are done.
The iOS permission prompt appears once, right after that. It is never shown at first launch and never repeated. Signing out and in again does not re-ask.
If you allow notifications, the app registers with Apple and Portal keeps a fingerprint of the registration, shown under Portal Devices, then Push Notifications. A rotated token is re-registered automatically.
If you decline, approvals keep working from the in-app inbox. To turn push on later, allow notifications for Portal Authenticator in iOS Settings, then tap Retry under Portal Devices, then Push Notifications.
Disable Push on the same screen turns it off in Portal. Signing out or revoking the phone turns it off as well.

What a notification does when you tap it:

Approval prompt (“Confirm code 042 to continue”): opens the Portal tab. If the matching number-match sheet is already open, the codes are cross-checked. If it is not open, a banner explains that the prompt is not on this phone and that a notification alone cannot approve.
Access request needs your approval or Approval overdue: refreshes the inbox and opens that request. If it is no longer pending, the list opens with a note saying so. If it belongs to a different tenant than the one you are signed in to, the app says that instead of switching.

The app icon badge and the counter on the Portal tab show how many decisions are waiting for you. They clear as you decide and when you sign out.

Once a linked iPhone is turned on for sign-in, you can sign in to Portal in a browser without typing a password, or use the phone as your second factor.

Turn it on

Right after linking, the app offers Use this iPhone to sign in once. You can also switch it on later:

in the app, on the Devices tab, or
in Portal, under Profile, then Linked Devices, with Use for sign-in.

If the phone is not eligible, both places say why: your organisation’s policy does not allow phone sign-in, the phone needs verification, the app needs an update, or the phone was revoked. Once a phone is enabled, Portal expects it at sign-in: someone with no other factor is asked to approve on the phone after their password, and can also skip the password.

Administrators control this under the tenant sign-in policy: enabled, second factor only, or disabled. An organisation that requires phishing-resistant sign-in cannot use phone approval as a factor; use passkeys instead.

Sign in

On the sign-in page, enter your email and choose Sign in with your phone. Portal shows a 3-digit code and starts a 2-minute countdown. Every enabled phone gets a Sign-in request notification. The notification carries no code and cannot approve anything.
Tap the notification, or open the app and the Phone Sign-In list. The pending request shows the tenant, the time and the requesting browser, for example “Chrome on macOS” and its IP address. Type the code the browser is showing and tap Approve.
The browser finishes and lands you in Portal with your second factor satisfied.

Password, authenticator code, recovery code and passkey stay available on the same screen. If your phone is off or offline, use one of them.

You have 3 tries to enter the code. A wrong entry says how many remain. The third wrong entry denies the request, and you start again from the browser. If the browser’s code has expired, the phone says so and nothing is approved.

Approve after a password

When you signed in with a password and Portal asks for a second factor, choose Approve on your phone. It appears only when Portal knows you have an enabled phone. The same request appears on the phone; approving it completes the second factor. Use a code instead cancels the phone request and lets you type an authenticator code.

This wasn’t me

If a sign-in request appears that you did not start, tap This wasn’t me. Do not ignore it. Portal denies the request, pauses phone sign-in for your account for 1 hour by default, records the report, and notifies your administrators through their Webhooks subscriptions. Repeated unanswered or dismissed requests pause it the same way: 3 inside 15 minutes by default. Your password, authenticator codes, recovery codes and passkeys keep working while phone sign-in is paused.

The pause lifts on its own when the time is up. To lift it sooner, use Resume now on the Phone sign-in paused banner under Profile, then Linked Devices. The phone shows the pause but cannot lift it. An administrator can also clear it from the person’s page with Unlock, which clears a password lockout at the same time and is recorded with their name.

Turn it off

Switch the phone off for sign-in on the app’s Devices tab or under Profile, then Linked Devices. Approving access requests from the phone is not affected. Revoking the phone, turning off two-factor sign-in, or an administrator MFA reset also turns sign-in off for it, and any request waiting on that phone is cancelled.

For administrators

Every pairing, revoke, automatic revoke, push registration, sign-in approval, denial and pause appears in your tenant’s audit log under the person’s name. A person’s page shows their phone sign-ins under Sign-in activity.
Users, then a person’s page, shows their linked phones. A linked phone is workflow assurance only: Portal does not check device compliance, operating-system patch state, disk encryption, jailbreak status or MDM enrolment, and offers no device-based conditional access. Do not present linked-phone counts as managed-endpoint evidence in a security questionnaire. Organisations that need managed-endpoint posture still need an MDM.
The default limits (5 active phones per person, 180 dormant days, 3 code tries, a 2-minute sign-in window, 1-hour pause after 3 unanswered requests in 15 minutes) are deployment and tenant policy settings. Ask Cadres support to change deployment defaults; the pause thresholds are under your tenant’s sign-in policy.

When something goes wrong

Symptom	Likely cause	What to do
Pairing code expired	More than 5 minutes passed	Select Pair Mobile Device again
Pairing refused at the limit	5 active phones already	Revoke an unused phone, then complete the pairing
Pairing cancelled after wrong codes	5 wrong Short code entries	Start a new pairing
The app says Portal signed this phone out	The phone was revoked, went dormant, or was re-paired	Pair again, then sign in
Approval refuses to continue	Prompt expired, or the notification code differed	Cancel and start the action again; deny it in Portal if it was not you
Approval says the device needs verification	Attestation missing	Revoke the phone and pair it again from the app
No sign-in notification arrives	Notifications declined, or push not enabled on this Portal	Open the app and choose the pending request from Phone Sign-In
Phone sign-in paused	Unanswered requests, or This wasn’t me	Sign in another way; resume under Profile, Linked Devices, or wait an hour
Codes lost after restoring an iPhone	Secrets stay on the original device	Use Repair with the key from the service or your export, or restore from your vault