> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botshield.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Register your app for BotShield passkeys

> Before your native app can run a BotShield passkey inline, botshield.ai has to name your app. Register your iOS app ID or Android package and signing fingerprint, and BotShield approves it.

A BotShield passkey belongs to the relying party `botshield.ai`. iOS and Android let your app use it only when `botshield.ai` vouches for your app in its `.well-known` files. Registering your app puts it there.

You need this only for the [inline passkey](https://docs.botshield.ai/native/inline-passkey.md). The [Open BotShield](https://docs.botshield.ai/native/open-botshield.md) hand-off needs no registration.

## What you register

> [tab] iOS
>
> | Field | Format | Example |
> | - | - | - |
> | App ID | `TEAMID.bundle.id`: your 10-character Apple Team ID, a dot, then the bundle ID | `ABCDE12345.com.example.app` |
>
> Find the Team ID in your Apple Developer account under **Membership**, and the bundle ID in Xcode under **Signing & Capabilities**. The Team ID is upper-case letters and digits.

> [tab] Android
>
> | Field | Format | Example |
> | - | - | - |
> | Package name | Your `applicationId` | `com.example.app` |
> | SHA-256 signing-certificate fingerprints | 1 to 5, each 32 bytes as `AA:BB:…` | `14:6D:E9:83:…:4E:9A` |
>
> Register the fingerprint of every key that signs a build people install: the Google Play app signing key (Play Console, **Test and release → App integrity**) and, if you test with it, your upload or debug key. `keytool -list -v -keystore <file>` prints a keystore's SHA-256. Lower-case or unseparated hex is accepted and normalized.

An app ID or package can be registered to one BotShield organization at a time.

## How approval works

1. **You ask.** An admin of your BotShield organization registers the app. Every new registration starts as **pending**.
2. **BotShield reviews it.** A registration changes files that Apple and Google trust on `botshield.ai`, so a BotShield admin approves each one. It is then **approved** or **rejected**.
3. **It goes live.** An approved app appears in `botshield.ai`'s files within about an hour. Apple's and Google's own caches can take longer to pick it up on a device.
4. **You can remove it** at any time, with no review. It leaves the files within the hour.

Your app's ID or package and fingerprints are published in those files, as the formats require. Your organization's name is not.

> [!NOTE]
>
> The Console has no screen for this yet. To register an app, contact your BotShield representative with the details above and your Organization ID (**Settings → Developer Tools → API Keys**).

## Set up your app

> [tab] iOS
>
> Add the **Associated Domains** capability to your app target and this entry:
>
> ```xml theme={null}
> <key>com.apple.developer.associated-domains</key>
> <array>
>   <string>webcredentials:botshield.ai</string>
> </array>
> ```
>
> Keep your own `applinks:` and `webcredentials:` entries for your domains. This one is in addition.
>
> Once BotShield approves your app, `https://botshield.ai/.well-known/apple-app-site-association` lists it under `webcredentials.apps`:
>
> ```json theme={null}
> { "webcredentials": { "apps": ["C7ZJDGDJ6P.botshield.app", "ABCDE12345.com.example.app"] } }
> ```
>
> iOS fetches that file through Apple's CDN when the app is installed or updated, not on every launch. If you test before approval, reinstall the app after approval. For a development build, `webcredentials:botshield.ai?mode=developer` makes iOS read the file directly, on a device with **Associated Domains Development** turned on in Developer settings.

> [tab] Android
>
> Once BotShield approves your app, `https://botshield.ai/.well-known/assetlinks.json` carries a statement for it:
>
> ```json theme={null}
> {
>   "relation": ["delegate_permission/common.get_login_creds"],
>   "target": {
>     "namespace": "android_app",
>     "package_name": "com.example.app",
>     "sha256_cert_fingerprints": ["14:6D:E9:83:…:4E:9A"]
>   }
> }
> ```
>
> Credential Manager reads that file to let your app use `botshield.ai` passkeys. BotShield also accepts your app's WebAuthn origin, `android:apk-key-hash:<base64url of the SHA-256>`, for the inline passkey. You add nothing to your manifest for passkeys.
>
> > [!WARNING]
> >
> > Android has not been run end to end yet. See [Android](https://docs.botshield.ai/native/inline-passkey.md#android).

## Check it

| Check | How |
| - | - |
| Your app is approved | `https://botshield.ai/.well-known/apple-app-site-association` or `assetlinks.json` lists it. |
| The device sees it | Run the [inline passkey](https://docs.botshield.ai/native/inline-passkey.md). `DOMAIN_NOT_ASSOCIATED` (Capacitor) or an Apple error that the app is not associated with `botshield.ai` means the device hasn't picked up the file, or the entitlement is missing. |
| The origin is accepted | `passkey-complete` returns `verified`, not `failed` with `assertion_invalid`. |

## Staging and production

`botshield.ai` serves one set of files, built from BotShield's **production** registry. Development and Production keys use the same passkeys and the same files, so one approval covers both.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.