Sign inGet Started

Verify customer identity in Apple Messages

Connect your identity provider once, then ask customers to sign in from an Apple Messages conversation. An agent can send the request from the dashboard, or your backend can send it through the API. Bird validates the provider's response and makes the verified identity available in the conversation and to your integration.

Bird never persists or returns customer access tokens, refresh tokens, ID tokens, or authorization codes. If your backend needs tokens, obtain them through your own identity provider integration, separately from Bird's verification flow. Verification records who signed in at that time; it does not establish an ongoing login session or grant an agent access to your systems.

Before you start

You need a connected Apple Messages business, permission to manage its settings and send replies, and access to your identity provider and Apple Business Register. A verification request requires an open conversation and a customer device that advertises authentication support (AUTH2).

Your provider must support:

  • OpenID Connect discovery at <issuer>/.well-known/openid-configuration. The document's issuer must exactly match the issuer you enter in Bird, including a trailing slash when present.
  • Authorization code flow with S256 PKCE and a nonce, returning a signed ID token.
  • openid, plus profile when you collect the customer's name and email when you collect their email.
  • One of the client authentication methods described below.

Apple's authentication reference requires the provider's OAuth endpoints to present a valid Extended Validation (EV) certificate. Saving provider settings in Bird does not establish Apple approval or device compatibility.

Connect your identity provider

Provider configuration is a dashboard task, including for API integrations. The same configuration serves both ways of requesting verification.

  1. Open Apple Messages businesses, choose your business, and open Settings > Customer authentication. Keep Enable authentication requests off while configuring the provider.

  2. Follow the provider setup instructions for your service. Register the callback URL for your Bird region:

    RegionCallback URL
    EUhttps://eu1.platform.bird.com/v1/amb/authentication/callback
    UShttps://us1.platform.bird.com/v1/amb/authentication/callback
  3. Enter the application's details in Bird. Settings save automatically when the required values are complete.

    FieldWhat to enter or select
    Provider issuer URLThe HTTPS issuer from discovery, without the /.well-known/openid-configuration suffix.
    Client IDThe identifier of the application you created with the provider.
    Client authenticationThe method registered for the application. Use the mode table below.
    Client secretThe application's secret for a secret-based mode. Bird encrypts this integration credential and does not display it again. Leave blank to retain a saved secret when the issuer, client ID, and mode are unchanged.
    Public signing keyFor Bird signing key mode, copy the public JWK shown after settings save and register it with the provider. Bird generates and protects the private key.
    Request the customer’s nameRequests profile and retains the name when the provider supplies it.
    Request the customer’s emailRequests email and retains the email and the provider's email verification claim when supplied.
    Callback URLThe displayed redirect URL to register with the provider. Check that it matches your region.
    Enable authentication requestsTurn on after provider and Apple registration are ready. Leave off while registering a signing key.
  4. If you chose Bird signing key mode, wait for the final issuer and client ID to save, then register the displayed Public signing key with the provider. Changing the issuer or client ID, switching to Bird signing key mode, or using Replace signing key creates a new key. Register the current key before enabling requests.

  5. In Apple Business Register, register the same client ID and the authorization endpoint from the provider's discovery document. Complete Apple's review of the authentication details, then turn on Enable authentication requests in Bird.

Choose a client authentication mode

Bird labelProvider methodWhen to choose it
Bird signing key (private_key_jwt)private_key_jwtPrefer this when the provider accepts Bird's public JWK for RS256 client assertions. Bird keeps the private key.
Client secret in authorization headerclient_secret_basicUse when the provider authenticates the application with its client ID and secret in the HTTP authorization header.
Client secret in request bodyclient_secret_postUse when the provider expects the client ID and secret in the token request body.

PKCE protects the code exchange in each mode; it does not replace client authentication. Choose a method the provider advertises in discovery and enables for your application.

Provider setup

Use your provider's section to create the application and complete the shared settings above.

Amazon Cognito

  1. In the Amazon Cognito console, open your user pool's App clients and create a Traditional web application with a client secret.
  2. Configure a user pool domain so the authorization and token endpoints are available. Add Bird's regional callback to Allowed callback URLs and enable the authorization code grant.
  3. Allow openid, plus profile and email for the collection options you enable. Give the app client read access to the corresponding user attributes.
  4. Enter the user pool issuer in Bird, typically https://cognito-idp.REGION.amazonaws.com/USER_POOL_ID. Pools using the updated issuer use https://issuer-cognito-idp.REGION.amazonaws.com/USER_POOL_ID. Copy the configured issuer exactly; the managed login domain is a different URL.
  5. Choose Client secret in authorization header (client_secret_basic) and enter the app client's ID and secret. Cognito also supports client_secret_post; its token endpoint supports these two secret-based modes.

See AWS's app client settings, token endpoint, and issuer endpoints.

If your backend needs its own ID, access, and refresh tokens after verification, it can implement a separate Cognito CUSTOM_AUTH flow through AdminInitiateAuth and AdminRespondToAuthChallenge. Your backend must map the verified identity to your Cognito user and implement its own challenge verification. The user-pool Lambda triggers also serve InitiateAuth; using the admin API does not replace verifying challenges before telling Cognito to issue tokens. Follow AWS's custom authentication challenge guide.

Auth0

  1. In the Auth0 Dashboard, open Applications > Applications, create an application, and choose Regular Web Applications.
  2. Add Bird's regional callback to Allowed Callback URLs. Enable the authorization code grant for the application and the connections your customers use.
  3. In Bird, enter the issuer as https://YOUR_AUTH0_DOMAIN/, preserving the trailing slash from discovery. Use the same tenant or custom domain throughout the configuration.
  4. In Auth0, under Credentials, select Client Secret (Basic). In Bird, choose Client secret in authorization header and enter the application's client ID and secret. This uses Auth0's secret authentication without its Enterprise-only private key JWT feature.
  5. Request openid, plus profile and email for the collection options you enable.

See Auth0's application settings, credential configuration, and issuer format.

Okta

  1. In the Okta Admin Console, create an app integration with OIDC - OpenID Connect as its sign-in method and Web Application as its type. Enable Authorization Code and register Bird's callback under Sign-in redirect URIs.
  2. Find the issuer: for the org authorization server, use https://YOUR_OKTA_DOMAIN. For a custom authorization server, use its issuer, such as https://YOUR_OKTA_DOMAIN/oauth2/AUTHORIZATION_SERVER_ID.
  3. In Bird, enter that Provider issuer URL and the app's Client ID, then choose Bird signing key (private_key_jwt). Keep Enable authentication requests off and wait for the settings to save and Public signing key to appear.
  4. In Okta, open the app's General tab, edit Client Credentials, and select Public Key / Private Key. Under Public Keys > Add Key, paste the displayed Bird public JWK and save. This lets Bird authenticate without sharing a client secret.
  5. Allow openid, plus profile and email as needed, and assign the application to the users who can sign in. Require Proof Key for Code Exchange (PKCE) for the app.

See Okta's OIDC app setup, public key registration, and authorization server issuers.

Microsoft Entra ID

  1. In the Microsoft Entra admin center, open Entra ID > App registrations > New registration. Register an application in the tenant whose users will sign in.
  2. Open Authentication, add a Web platform, and enter Bird's callback under Redirect URIs.
  3. In Bird, enter the tenant-specific issuer https://login.microsoftonline.com/TENANT_ID/v2.0. Use the directory's tenant ID so discovery returns the exact issuer Bird validates.
  4. Create a client secret under Certificates & secrets. In Bird, choose Client secret in request body (client_secret_post), which matches Microsoft's documented confidential web application token request. Enter the Application (client) ID and secret value.
  5. Request openid, plus profile and email as needed. Treat email as display data; Microsoft's email claim can change and is not suitable for authorization.

See Microsoft's app registration, redirect configuration, authorization code flow, and ID token claims.

Google

  1. In your Google Cloud project's Google Auth platform, configure the consent screen and create an OAuth client with Web application as its application type.
  2. Add Bird's regional callback to Authorized redirect URIs. The URL must match exactly.
  3. In Bird, enter https://accounts.google.com as the issuer and the OAuth client's ID and secret. Choose Client secret in request body (client_secret_post) to match Google's documented code exchange.
  4. Request openid, plus profile and email for the collection options you enable. Configure the consent audience for the customers who will sign in.

Google's discovery document advertises S256 PKCE and the two secret-based client authentication methods. See Google's OpenID Connect guide, web application setup, and discovery metadata.

Keycloak

  1. In the Keycloak Admin Console, select your realm and create an OpenID Connect client under Clients.
  2. Turn on Client authentication and Standard Flow. Add Bird's callback to Valid Redirect URIs, using the exact URL. Set PKCE method to S256.
  3. In Bird, enter the realm issuer, such as https://YOUR_KEYCLOAK_HOST/realms/YOUR_REALM. Include any deployment path that appears in the issuer.
  4. Use the client's secret from Credentials. In Bird, choose Client secret in authorization header (client_secret_basic), which Keycloak supports for confidential clients, and enter the client ID and secret.
  5. Request openid and keep the profile and email client scopes linked when those collection options are enabled. Their protocol mappers determine which claims appear.

See Keycloak's client configuration, client scopes, and discovery endpoint. The realm and client settings must permit the users and claims your business needs.

Ping Identity (PingOne)

  1. In the PingOne admin console, open Applications > Applications and create an OIDC Web App.
  2. Under Configuration, select the Authorization Code grant and Code response type. Add Bird's callback to Redirect URIs and require S256 PKCE.
  3. Read the issuer from your environment's OIDC discovery document. An example is https://auth.pingone.com/ENVIRONMENT_ID/as; use your environment's regional domain. In Bird, enter this Provider issuer URL and the Client ID shown on PingOne's Configuration tab. Choose Bird signing key (private_key_jwt), keep Enable authentication requests off, and wait for settings to save and Public signing key to appear.
  4. In PingOne, select Private Key JWT for Token Endpoint Authentication Method and JWKS for JSON Web Key Set Method. Paste Bird's current public JWK as a key set, {"keys":[PUBLIC_JWK]}, replacing PUBLIC_JWK with the displayed JSON object, then save. PingOne uses this key set to validate Bird's RS256 client assertions.
  5. Allow openid, plus profile and email as needed, and enable the app for the intended users.

See PingOne's web app creation, OIDC settings, and client authentication methods.

OneLogin

  1. In the OneLogin Admin UI, open Applications > Add App, search for OpenId Connect (OIDC), and create the application. Assign it to the users who can sign in.
  2. On the app's Configuration tab, add Bird's callback to Redirect URIs.
  3. In Bird, enter https://YOUR_SUBDOMAIN.onelogin.com/oidc/2 as the issuer. The app's OpenID Provider Configuration Information link opens its discovery document.
  4. On SSO, set the token endpoint Authentication Method to Basic. In Bird, choose Client secret in authorization header (client_secret_basic) and enter the application's client ID and secret.
  5. Request openid, plus profile and email as needed. OneLogin's discovery document advertises S256 PKCE and client_secret_basic and client_secret_post authentication.

See OneLogin's OIDC application connection, provider configuration, and authorization request.

Salesforce

  1. In Salesforce Setup, create a local external client app and select Enable OAuth. Add Bird's callback under Callback URL.
  2. Allow openid, plus the identity scopes for profile and email as needed. Enable Configure ID token and Include Standard Claims. The ID token audience must include the client ID you enter in Bird.
  3. Select Require Secret for the Web Server Flow and Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows.
  4. In Bird, enter https://login.salesforce.com as the issuer for production Salesforce sign-in. Salesforce also publishes discovery for My Domain and Experience Cloud sites; use the returned issuer and check that it serves discovery at the same base URL before configuring Bird.
  5. Choose Client secret in request body (client_secret_post). Enter the app's consumer key as Client ID and consumer secret as Client secret. Salesforce supports this mode for the token exchange.

See Salesforce's external client app OAuth settings and discovery reference. New connected app creation is restricted; use the external client app setup for a new integration.

FusionAuth

  1. In the FusionAuth admin UI, create an application under Applications for your default tenant. On OAuth, enable the authorization code grant and add Bird's callback to Authorized redirect URLs.
  2. Configure the default tenant's Issuer as the public HTTPS base URL, such as https://YOUR_FUSIONAUTH_HOST, and enter that exact URL in Bird. The discovery endpoint without a tenant identifier uses the default tenant.
  3. Set Client Authentication and PKCE to Required. In Bird, choose Client secret in authorization header (client_secret_basic) and enter the application's client ID and secret. FusionAuth advertises this mode in discovery.
  4. Allow openid. On the application's Scopes tab, enable the provided profile and email scopes for the collection options you use. Use an RS256 ID token signing key that is published through the provider's signing-key endpoint.

See FusionAuth's application settings, tenant issuer, discovery document, and scope configuration.

Request verification

Once the provider is enabled, choose the dashboard or API flow. Both send Apple's native sign-in message and use the same verification process.

From the dashboard

  1. Open Conversations and select an open conversation.
  2. Choose Request > Verification request, then Request authentication.
  3. Ask the customer to open the verification message and sign in with your provider.

From your backend

Create a workspace API key with amb:write to request verification and amb:read to read the result. Register a webhook endpoint subscribed to amb.authentication.updated; managing the endpoint requires webhooks:write.

The examples use Bash with curl, jq, and uuidgen. Set your API key, regional API base URL, and an open conversation ID. Reply through the Apple Messages API explains the regional URLs and finding a conversation. Read its device_capabilities to check for AUTH2.

Code example
export BIRD_API_KEY="<your API key>"
export BIRD_API_URL="<your region's API base URL>"
export CONVERSATION_ID="<an open conversation ID>"

Send Request conversation authentication with an idempotency key. The request has no body.

Code example
REQUEST_ID="$(uuidgen)"
AUTHENTICATION="$(curl --fail-with-body -sS -X POST \
  "$BIRD_API_URL/v1/amb/conversations/$CONVERSATION_ID/authentications" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Idempotency-Key: $REQUEST_ID")"
AUTHENTICATION_ID="$(jq -r .id <<<"$AUTHENTICATION")"
jq . <<<"$AUTHENTICATION"

A 202 response returns the request with status set to pending. Keep its id to read the result. The request expires ten minutes after created_at.

If the POST HTTP request times out without a response, retry with the same REQUEST_ID to recover its original response. To request sign-in again after an expired, failed, or cancelled attempt, generate a new REQUEST_ID and send another POST. A new request supersedes an unfinished one in the same conversation.

Read the result

After signing in, the customer must return to Messages so their device can confirm the original request. The request remains processing until that confirmation arrives. If it does not arrive within one minute after the provider callback, the request fails and the customer needs a new sign-in request.

After verification, Bird tries to send a short confirmation message. Use the verified identity or request status as evidence; a missing confirmation message does not undo verification.

In the dashboard

The conversation's Identity status shows Verified after a successful verification. Customer details show the name and email when requested and supplied. The identity details include the verification time and provider. Previously verified identifies a historical result, such as after the conversation reopens or provider settings change.

The request shows Waiting for the customer, then Verifying identity while sign-in completes. It also shows cancellation, failure, expiry, or replacement. After failure or expiry, use Request authentication again.

In your backend

Bird publishes amb.authentication.updated when a request reaches a terminal status. Publication is best effort, so an event can be missed even when the request completed. Requests superseded by a business disconnection produce no event. The event includes data.workspace_id and data.business_account_id for routing. Its data.authentication is the same resource that Get an authentication request returns.

Code example
{
  "type": "amb.authentication.updated",
  "timestamp": "2026-11-11T09:14:27Z",
  "data": {
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "business_account_id": "abz_01krdgeqcxet5s7t44vh8rt9mg",
    "authentication": {
      "id": "amauth_01krdgeqcxet5s7t44vh8rt9mg",
      "conversation_id": "acv_01krdgeqcxet5s7t44vh8rt9mg",
      "provider_id": "aauthp_01krdgeqcxet5s7t44vh8rt9mg",
      "provider_revision": 3,
      "message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
      "status": "succeeded",
      "created_at": "2026-11-11T09:13:02Z",
      "expires_at": "2026-11-11T09:23:02Z",
      "completed_at": "2026-11-11T09:14:27Z",
      "identity": {
        "issuer": "https://login.example.com",
        "subject": "customer-48213",
        "name": "Avery Stone",
        "email": "avery@example.com",
        "email_verified": true,
        "verified_at": "2026-11-11T09:14:27Z"
      }
    }
  }
}
StatusMeaning
pending, processingSign-in is still in progress. These states do not produce outcome events.
succeededBird validated the provider's response and received confirmation from the originating Messages device. identity is present.
cancelledThe customer or provider declined the sign-in.
failedSending or provider validation failed, the device confirmation failed or did not arrive in time, or the callback was reused. Read failure_code.
expiredTen minutes passed without a result.
supersededA newer request, conversation change, provider change, or business disconnection replaced this request.

Route the event by data.workspace_id and data.business_account_id. Map data.authentication.identity.issuer and data.authentication.identity.subject to your customer record. name and email appear only when you enabled collection and the provider supplied them. email_verified preserves the provider's claim; Bird does not infer it.

Verify the webhook signature and deduplicate on webhook-id. The same event can arrive more than once. If no event arrives by expires_at, read the request:

Code example
curl --fail-with-body -sS \
  "$BIRD_API_URL/v1/amb/conversations/$CONVERSATION_ID/authentications/$AUTHENTICATION_ID" \
  -H "Authorization: Bearer $BIRD_API_KEY" | jq .

The read can briefly trail a newly received event. Get a conversation also returns authentication, with the latest request and last verified identity. Its historical flag is true when the conversation or provider changed after verification.

Troubleshoot verification

  • Provider settings fail to save or sign-in fails: check the exact issuer, callback URL, client ID, and authentication mode. For signing key mode, check that the provider has Bird's current public key.
  • Name or email is missing: check Bird's collection switches and the application's scopes and claims.
  • The request cannot start: confirm that the business is connected, its provider is enabled, the conversation is open, and the device advertises AUTH2. A closed conversation must be reopened by the customer.
  • An API request returns 403: grant the required amb permission. A 404 means the conversation or authentication request does not exist in this workspace. A 422 explains a condition preventing the request, such as a closed conversation or missing provider.
  • No outcome event arrives: read the authentication request using its saved ID before deciding whether to send another request.

See Apple Messages troubleshooting for device and conversation checks.

Continue with the documentation, guides and examples for this topic.