---
title: Identities and passkeys
description: Add or remove a way to sign in to your account, manage passkeys, and understand security notices.
slug: /guides/identities-and-passkeys
order: 2
visibility: public
redirects_from: []
---

# Identities and passkeys

Prompt:

> Add my GitHub sign-in to the same account.

Also works:

- "Which passkeys work on this site?"
- "I lost the phone that held my passkey. Remove it."

An identity is one way to sign in to your account, such as Google, GitHub, or a code sent to your email. A passkey lets you sign in without waiting for that emailed code.

To add a second identity, your AI tool calls `link_identity`. You then finish the link in your browser within ten minutes ([step 1](#1-link-a-second-sign-in)). You add and remove passkeys yourself, in your browser. The platform offers a passkey after you sign in by emailed code, and the passkey page at `https://turnzero.ai/auth/passkeys` adds or removes one at any time. No tool action does either ([step 2](#2-register-and-remove-passkeys)).

You remove a sign-in method yourself on Account & security ([step 4](#4-remove-a-sign-in-method)). Your AI tool cannot remove it.

## What your AI tool does

- Calls `read_account` first, to list your account's identities and how many passkeys it has.
- For "add my GitHub sign-in", calls `link_identity` and gives you the `link_url` it returns. It then calls `read_account` to check that the new identity is listed.
- For a passkey, gives you the passkey page's address, `https://turnzero.ai/auth/passkeys`. You add and remove passkeys in your browser; the tool has no action that does it.
- To remove a sign-in method, directs you to Account & security, `https://turnzero.ai/dashboard/account`. You review and confirm the removal there.
- For a passkey on an account that signs in only with Google or GitHub, tells you to sign in by emailed code once first. Use `https://turnzero.ai/sign-in` and the email address that sign-in verified. It identifies this case from `read_account`: no identity has provider `email`.
- Asks you to open the link in a browser within ten minutes and sign in with the other provider. It writes nothing into your project. It changes nothing on your account unless you ask.

## What you need

- A web browser. To link a second sign-in method, you also need an account with that other provider.
- For a passkey, an account that signs in by emailed code, and a device or password manager that can store a passkey. If your account signs in only with Google or GitHub, first sign in by code at the email address that sign-in verified.

## Before your AI starts

**For the AI tool:** Check the following before starting.

- A connected, signed-in AI tool ([Connect your AI assistant](https://turnzero.ai/cloud/getting-started/connect-your-tool/)).

## Steps

### 1. Link a second sign-in

`read_account` lists your account's identities. Each one shows its provider and its subject, the ID that provider uses for you. For an emailed code, the subject is your address.

Call `link_identity` with no arguments. It returns `link_url`, valid for ten minutes, and `expires_in: 600`:

```json
{
  "contract_version": 1,
  "reference": "0a1b2c3d4e",
  "link_url": "https://turnzero.ai/link/<one-time ticket>",
  "expires_in": 600
}
```

You open the link in a browser and, if asked, sign in to the account you are adding to with a method already linked to it. Then sign in with the other provider. `read_account` then lists the new identity. The platform never links two accounts because their email addresses match. If the identity you sign in with already belongs to another account, the link is refused with `identity_already_bound`.

Say you sign in with Google or GitHub for the first time, and another account already uses that address. The page offers to link this sign-in to that account instead. It also offers to send a code to that address.

#### The emailed code

Say your account already uses an address through Google or GitHub. If you sign in by emailed code at that same address, the code becomes a sign-in method of that account. It does not create a second account. `read_account` then lists an identity with provider `email` and the address as its subject.

A code works for ten minutes and allows five tries. A sixth wrong entry ends the code, refused with `signin_code_invalid`. One address gets at most five codes an hour. Ten wrong entries for one address within an hour also block its next code. Past either limit, a new code is refused with `signin_code_rate_limited` until the hour passes. [Connect your AI assistant](https://turnzero.ai/cloud/getting-started/connect-your-tool/) shows the sign-in itself.

After a permanent delivery failure or a spam complaint, the mail provider holds an address inactive, so no sign-in code arrives. This applies to your account's codes and to codes sent to your application's users. Email [Turn Zero support](mailto:support@turnzero.ai) to ask for the block to be lifted for you or one of your users.

### 2. Register and remove passkeys

A passkey is a faster way to sign in by emailed code: it signs you in without waiting for the code. Right after you sign in by emailed code, the platform offers to add a passkey, if your account has none that works on this site. A sign-in with Google or GitHub offers none. So an account that signs in only with Google or GitHub is never offered a passkey.

To add a passkey to such an account, open `https://turnzero.ai/sign-in` and sign in by code once at the email address your Google or GitHub sign-in verified. You do not need to sign out first. That adds the code to your account, as step 1 says, and the offer follows.

A code sent to another address creates a new account instead. If your account has no emailed-code sign-in, the passkey page explains how to add one, in place of its **Add a passkey** button.

If you decline the offer, it comes back after thirty days. The passkey page adds a passkey at any time. There is one exception to the offer. When you sign in to approve a waiting request, the sign-in goes straight to that request, and the offer waits for your next sign-in by code. A passkey works only on the platform's own site, so it cannot be used on a look-alike site.

The offer stays open for ten minutes. The offer depends on a cookie in your browser, and signing that browser out clears it. The platform then offers the passkey again at your next sign-in by code.

When you click or tab into the email field on the sign-in page, the page offers your saved passkey. After the email form's submit button, choose **Sign in with a passkey** to use a passkey on a security key or another device.

The passkey page, `/auth/passkeys`, adds and removes passkeys later. Signing out does not remove a passkey: it ends your sessions, and your passkeys stay registered. To remove one, confirm with any passkey of your account.

If no passkey completes that confirmation, the page offers **Remove it without the passkey**. Use this when the device was lost or reset, or the passkey was deleted from it. You must have signed in within the last eight hours, using any of your account's sign-in methods. The removed passkey stops signing in at once. You can undo the removal for three days, as described below.

The page lists each passkey by name. Beside it are the date it was added and when it last signed you in, in your own time zone. A new passkey is named after its password manager, such as Google Password Manager or iCloud Keychain. Otherwise it is named after the browser and system that added it, such as Chrome on Windows. **Rename** gives it your own name, up to 64 characters. **← Account & security**, at the top and bottom of the page, returns to the dashboard.

Under your own signed-in session, `read_account` also returns `passkeys`, with two counts. `held` is the number of your passkeys that work on this site. `stranded` is the number registered for another site. `passkeys` is `null` where passkeys are not offered.

For example, `read_account` could return the following for an account that added emailed-code sign-in to Google and registered one passkey. The values are invented, and other response members are left out.

```json
{
  "contract_version": 1,
  "reference": "5f6a7b8c9d",
  "account": {
    "id": "<your account id>",
    "created_at": "2026-03-04T15:20:11.000Z",
    "standing": "active",
    "identities": [
      { "provider": "google", "subject": "<the ID Google uses for you>" },
      { "provider": "email", "subject": "you@example.com" }
    ],
    "synthetic": false,
    "unbilled": false,
    "passkeys": { "held": 1, "stranded": 0 }
  }
}
```

You can undo a passkey change for three days after it, on the passkey page. You must have signed in within the last eight hours. Undoing an addition removes the passkey, and undoing a removal restores it. Either undo signs out every other session and connection of your account at once. The browser you undo from stays signed in.

An undo ends what Sign out everywhere ends, as [What ends a connection](https://turnzero.ai/cloud/concepts/sign-in-sessions-and-tokens/#what-ends-a-connection) lists. A token you made with `mint_token` keeps working. The undo can answer `internal` and tell you to sign in again. If it does, sign in and run **Sign out everywhere**. The undo did go through, and Sign out everywhere ends any token the undo could not. The email notice below has no link: to undo, you sign in to the passkey page.

After you sign in with a passkey, the sign-in page tells your browser's passkey provider which of your passkeys still work. A passkey whose removal can still be undone still counts until its three days end. If you choose a passkey the platform does not have and cannot restore, the page tells the provider it is unknown. A provider that supports these signals can then hide or delete it. An application's own sign-in page does the same for its users. The sign-in never waits for the provider, and its result is the same either way.

### 3. Passkey notices

Adding or removing a passkey sends an email notice from `donotreply@turnzero.ai`. It goes to the addresses your identities have verified, at most five, the oldest first. One passkey sends no notice: the one you add at the offer right after the sign-in that created your account.

If an account has no emailed-code sign-in, the platform removes its passkey, at the latest the next time that passkey is used. It sends the same notice for that removal and records it the same way.

The notice says what changed and when. If you made the change, you need to do nothing. If you did not, sign in and review your passkeys. The notice has no link. The platform limits how many notices it sends, as [Manage end users](https://turnzero.ai/cloud/guides/manage-end-users/) states for end users. Your account's event record holds the change either way.

### 4. Remove a sign-in method

Before removing a sign-in, make sure a method you control still signs you in. Removal ends every browser session and connected AI tool, including the browser you use to remove it. Your passkeys and tokens minted with `mint_token` remain. Review those separately if you suspect someone else has access.

Open [Account & security](https://turnzero.ai/dashboard/account) and find Sign-in & security. Each row names the provider and its verified email address, or says it has no verified address. Choose Remove beside the sign-in you want to remove.

A row offers Remove only while your account has more than one sign-in method. An email-code row offers none if a provider row carries the same address. Signing in by code at that address would add it again.

Check the provider and address in the confirmation. If that provider's address also has an email-code sign-in, the confirmation offers to remove both. Review that choice: removing the provider alone leaves sign-in by emailed code at that address available.

The confirmation shows any change to your account email. Choose Remove sign-in, or Remove both sign-ins if you chose both. Cancel closes the confirmation without removing either.

The result lists the sign-ins removed and those remaining. If your account email changed, it shows the new one. Follow its sign-in link and use a remaining method you control. A security notice goes to the account's verified addresses, including the removed sign-in's verified address.

If the page cannot confirm whether removal happened, sign in again and check the sign-in methods. Do not treat being signed out as proof of removal.

#### The page refuses removal

Follow the page's explanation:

- Keep at least one sign-in with a verified address. Link another sign-in before removing the last one.
- Keep an email-code sign-in while your account has passkeys. To remove the last email-code sign-in, remove the passkeys first.
- If a sign-in was added less than three days ago, older sign-ins stay for three days after the newest addition. Wait until that period ends.
- Sign in again if your browser sign-in is more than eight hours old, then return to Account & security.
- A sign-in that provides administrator access cannot be removed on this page.
- If the page refuses because security notices are unavailable, nothing is removed. Try again later.

An AI tool or API token cannot remove a sign-in method. Use this page in a signed-in browser.

## Expected result

`link_identity` returns `link_url` and `expires_in: 600`. After you finish the link in a browser, `read_account` lists the new identity.

After a passkey change, `read_account` returns the new counts under `passkeys`, and the notice goes to your verified addresses, at most five. **Account & security**, `/dashboard/account`, shows your passkey standing and other sign-in methods under **Sign-in & security**. It links to the passkey page.

## Refusals

See the [refusals reference](https://turnzero.ai/cloud/reference/refusals/) for other platform errors.

From `identity_already_bound` down, the rows are refusals that the linking page, the sign-in page, and the passkey page show in your browser. An authenticator, named in some rows, is the device or password manager that holds a passkey.

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `app_credential_not_admitted` | 403 | The call ran under an application's [platform credential](https://turnzero.ai/cloud/concepts/glossary/#platform-credential), which only `read_account` accepts. | Use your signed-in session or a [minted token](https://turnzero.ai/cloud/concepts/glossary/#minted-token). |
| `authentication_required` | 401 | No credential matched an account. | Sign in again through your AI tool. |
| `account_suspended` | 403 | The account is suspended, so sign-ins and actions that need your identity are refused. | Wait for platform staff to reinstate the account, then sign in again. |
| `identity_already_bound` | 409 | The provider identity you tried to link already belongs to a different account. | Sign in to that account, or link a different identity. |
| `signin_code_invalid` | 400 | The sign-in code is wrong, expired, replaced, or from another browser. The sixth wrong try ends the code. | Type the code from the latest email, in the browser that asked for it, or choose Request a new code. |
| `signin_code_rate_limited` | 429 | Too many codes went to this address within the hour, or too many tries failed. Or the platform reached its limit on sending email. | Wait for the hour to pass, or sign in another way. |
| `sign_in_required` | 401 | No sign-in method is set up for the request, or a passkey page was opened in a browser that is not signed in. | Sign in first. For the passkey pages, sign in on the site, then open them. |
| `passkeys_not_configured` | 404 | Passkeys are not available, because the platform's passkey site or its email sender for codes is not set up. | Sign in another way. |
| `passkey_requires_email` | 409 | You asked to add a passkey to an account that does not sign in by emailed code. A passkey is a faster way to sign in by code. | Sign in by code once at the address your Google or GitHub sign-in verified, which adds the code to your account. Then add the passkey at that sign-in's offer or from the site's passkey page. |
| `offer_cookie_required` | 400 | The passkey offer was opened without the cookie the offer page set, or that browser signed out, which clears the cookie. | Return to the offer page before the offer ends, or add the passkey later from the site's passkey page. |
| `passkey_registration_refused` | 400 | The new passkey could not be verified. | Add it again from the site's passkey page. |
| `passkey_already_registered` | 409 | This passkey is already registered. | Use the registered passkey, or register a different authenticator. |
| `passkey_challenge_unknown` | 400 | The one-time code the platform gave for these passkey steps, called the challenge, is unknown, expired, or was made for another purpose. | Start the passkey steps again from the page. |
| `passkey_origin_mismatch` | 400 | The passkey steps ran on a site other than the platform's. | Run them from the sign-in page at `https://turnzero.ai`. |
| `passkey_rp_id_mismatch` | 400 | The authenticator names a site other than the platform's. | Run the passkey steps from the sign-in page at `https://turnzero.ai`. |
| `passkey_assertion_refused` | 400 or 401 | The passkey's answer could not be read (400), or its signature or user could not be verified (401). | Try the passkey again, or sign in another way and register it again. |
| `passkey_counter_regressed` | 403 | The authenticator's use count went backwards, which can mean someone copied the authenticator. | Sign in another way, remove the passkey from the site's passkey page, and register it again. |
| `passkey_unknown` | 404 | No passkey matches, or its account no longer exists. A passkey on an account that does not sign in by emailed code is removed and refused this way. | Sign in another way. To register a passkey again, sign in by emailed code and accept the offer. |
| `passkey_not_stranded` | 409 | You asked for the special removal of a passkey that still works on this site. | Use the ordinary removal on the passkey page. If no passkey can confirm it, use **Remove it without the passkey** after signing in within the last eight hours. |

## Related

- [Your account](/turnzero/guides/your-account/) shows the account, its identities, and its [standing](https://turnzero.ai/cloud/concepts/glossary/#standing).
- [Connect your AI assistant](https://turnzero.ai/cloud/getting-started/connect-your-tool/) covers your AI tool's sign-in.
- [Manage end users](https://turnzero.ai/cloud/guides/manage-end-users/) covers passkeys and notices for an application's own users.
- [Sign-in, sessions, and tokens](https://turnzero.ai/cloud/concepts/sign-in-sessions-and-tokens/) compares every credential, how long it lasts, and what ends it.
- [Glossary](https://turnzero.ai/cloud/concepts/glossary/) defines the terms used on this page.
- [link_identity](https://turnzero.ai/cloud/reference/actions/link-identity/) and [read_account](https://turnzero.ai/cloud/reference/actions/read-account/) in the generated reference give each action's arguments, result, and refusals.
