Skip to content

MFA, passkeys & sessions

Everything on your Account security page, and what each control actually protects you from.

Before you start: everything here is personal and needs only your own signed-in account — no role, no plan. All of it refuses personal and project access tokens, so it is a web-app or interactive-session task. Setting an organization-wide MFA policy is different: that needs the organization Admin role and is driven over the API. When you're done you will have at least two ways to prove it's you, recovery codes stored somewhere sensible, and a habit of reviewing sessions.

Passkeys

A passkey is a credential bound to your device's secure hardware and to appgantry.com. It can replace your password entirely or act as a second factor.

Passkeys are the strongest option here, because a passkey cannot be phished: it refuses to authenticate to a site that isn't AppGantry, no matter how convincing the page looks.

Add a passkey from Account security. Your browser or operating system does the rest — Touch ID, Windows Hello, a phone, or a hardware key. Name each one after the device so the list stays meaningful.

  • Up to 20 passkeys per developer.
  • Each can be renamed or removed individually.
  • Register at least two, on different devices, before you rely on passkeys for sign-in. One passkey on one laptop is one lost laptop away from a support ticket.

TOTP

TOTP is the six-digit-code flow from an authenticator app.

To enroll:

  1. Start enrollment; AppGantry shows a QR code.
  2. Scan it with your authenticator.
  3. Enter a current code to confirm.

The confirmation step exists so a half-configured authenticator can't lock you out: enrollment doesn't take effect until you've proved it works.

Codes are time-based, so if yours are rejected, check your device's clock.

Recovery codes

Enrolling in MFA issues recovery codes. Each is single-use, and they are shown once.

  • Store them somewhere you can reach without the device holding your authenticator. A password manager on another device, or printed and filed.
  • Regenerate if they're exposed or running low. Regenerating invalidates the previous set immediately.
  • Losing both your authenticator and your recovery codes means an identity-verification conversation with support. Don't rely on that.

Turning MFA off

You can disable MFA. Doing so requires re-authenticating, and it is recorded in your audit trail — as is enabling it, and regenerating recovery codes.

If your organization requires MFA, disabling it will simply stop you using the organization.

Organization MFA policy

An organization can require MFA of its members, with an optional grace period, and can decide whether a passkey satisfies the requirement.

Members without a factor get a clear prompt in the web app once the grace period is over; over the API they get HTTP 403 with mfa_enrollment_required.

If you're rolling this out to a team: announce it, set a grace period long enough for people to act, and enroll yourself first.

Policy is an API-level control today

The organization MFA policy is set through the API rather than a dedicated screen:

Operation Route
Read the current policy GET /api/v1/organizations/{organization_id}/mfa-policy
Set the policy PUT /api/v1/organizations/{organization_id}/mfa-policy

Organization Admin is required. Request and response shapes are in the interactive API reference.

Sessions

Every sign-in creates a session. Your account's session list shows each one — device, browser, approximate location, last used, and which is current — and lets you act:

Action Effect
Revoke one session That device can no longer renew; its access dies shortly after
Log out all devices Revokes every session including your own, and invalidates outstanding access tokens

Ordinary sign-out ends that session. Other devices you're signed in on stay signed in. That's usually what you want; when it isn't, use log out all devices.

Review sessions when a device is lost or stolen, when you see an unfamiliar sign-in in your audit trail, or periodically.

If you think your account is compromised

In this order:

  1. Change your password.
  2. Log out all devices.
  3. Regenerate recovery codes.
  4. Review your passkeys and remove any you don't recognise.
  5. Review and revoke your personal access tokens.
  6. Check your audit trail for Login succeeded and Refresh token reuse detected entries you can't explain.
  7. Tell your organization's admins, who should review the organization audit feed and any project access tokens you created.

Order matters: revoking sessions before changing the password just invites the attacker to sign in again.

A sensible baseline

  1. Two passkeys, on different devices.
  2. TOTP as a fallback, with codes stored in a password manager.
  3. Recovery codes stored somewhere else entirely.
  4. A unique, long password, from a password manager.
  5. A session review whenever a device changes hands.

See also