Register your app for BotShield passkeys

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. The Open BotShield hand-off needs no registration.

What you register

iOS
Android

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.

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

You ask. An admin of your BotShield organization registers the app. Every new registration starts as pending.
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.
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.
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.

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

iOS
Android

Add the Associated Domains capability to your app target and this entry:

<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:

{ "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.

Once BotShield approves your app, https://botshield.ai/.well-known/assetlinks.json carries a statement for it:

{
  "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.

Android has not been run end to end yet. See 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. `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.

Get Started

BotShield Gate

BotShield Actions

Verified Accounts

Native apps

Agents Ask

Webhooks

Server SDK

Console

Integrations

Concepts

Changelog

Register your app for BotShield passkeys

What you register

How approval works

Set up your app

Check it

Staging and production