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'sissuermust 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, plusprofilewhen you collect the customer's name andemailwhen 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.
-
Open Apple Messages businesses, choose your business, and open Settings > Customer authentication. Keep Enable authentication requests off while configuring the provider.
-
Follow the provider setup instructions for your service. Register the callback URL for your Bird region:
Region Callback URL EU https://eu1.platform.bird.com/v1/amb/authentication/callbackUS https://us1.platform.bird.com/v1/amb/authentication/callback -
Enter the application's details in Bird. Settings save automatically when the required values are complete.
Field What to enter or select Provider issuer URL The HTTPS issuer from discovery, without the /.well-known/openid-configurationsuffix.Client ID The identifier of the application you created with the provider. Client authentication The method registered for the application. Use the mode table below. Client secret The 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 key For 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 name Requests profileand retains the name when the provider supplies it.Request the customer’s email Requests emailand retains the email and the provider's email verification claim when supplied.Callback URL The displayed redirect URL to register with the provider. Check that it matches your region. Enable authentication requests Turn on after provider and Apple registration are ready. Leave off while registering a signing key. -
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.
-
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 label | Provider method | When to choose it |
|---|---|---|
| Bird signing key (private_key_jwt) | private_key_jwt | Prefer this when the provider accepts Bird's public JWK for RS256 client assertions. Bird keeps the private key. |
| Client secret in authorization header | client_secret_basic | Use when the provider authenticates the application with its client ID and secret in the HTTP authorization header. |
| Client secret in request body | client_secret_post | Use 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
- In the Amazon Cognito console, open your user pool's App clients and create a Traditional web application with a client secret.
- 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.
- Allow
openid, plusprofileandemailfor the collection options you enable. Give the app client read access to the corresponding user attributes. - Enter the user pool issuer in Bird, typically
https://cognito-idp.REGION.amazonaws.com/USER_POOL_ID. Pools using the updated issuer usehttps://issuer-cognito-idp.REGION.amazonaws.com/USER_POOL_ID. Copy the configured issuer exactly; the managed login domain is a different URL. - Choose Client secret in authorization header (
client_secret_basic) and enter the app client's ID and secret. Cognito also supportsclient_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
- In the Auth0 Dashboard, open Applications > Applications, create an application, and choose Regular Web Applications.
- Add Bird's regional callback to Allowed Callback URLs. Enable the authorization code grant for the application and the connections your customers use.
- 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. - 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.
- Request
openid, plusprofileandemailfor the collection options you enable.
See Auth0's application settings, credential configuration, and issuer format.
Okta
- 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.
- Find the issuer: for the org authorization server, use
https://YOUR_OKTA_DOMAIN. For a custom authorization server, use its issuer, such ashttps://YOUR_OKTA_DOMAIN/oauth2/AUTHORIZATION_SERVER_ID. - 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.
- 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.
- Allow
openid, plusprofileandemailas 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
- In the Microsoft Entra admin center, open Entra ID > App registrations > New registration. Register an application in the tenant whose users will sign in.
- Open Authentication, add a Web platform, and enter Bird's callback under Redirect URIs.
- 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. - 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. - Request
openid, plusprofileandemailas 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.
- 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.
- Add Bird's regional callback to Authorized redirect URIs. The URL must match exactly.
- In Bird, enter
https://accounts.google.comas 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. - Request
openid, plusprofileandemailfor 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
- In the Keycloak Admin Console, select your realm and create an OpenID Connect client under Clients.
- Turn on Client authentication and Standard Flow. Add Bird's callback to Valid Redirect URIs, using the exact URL. Set PKCE method to S256.
- In Bird, enter the realm issuer, such as
https://YOUR_KEYCLOAK_HOST/realms/YOUR_REALM. Include any deployment path that appears in the issuer. - 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. - Request
openidand keep theprofileandemailclient 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)
- In the PingOne admin console, open Applications > Applications and create an OIDC Web App.
- Under Configuration, select the Authorization Code grant and Code response type. Add Bird's callback to Redirect URIs and require S256 PKCE.
- 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. - 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]}, replacingPUBLIC_JWKwith the displayed JSON object, then save. PingOne uses this key set to validate Bird's RS256 client assertions. - Allow
openid, plusprofileandemailas needed, and enable the app for the intended users.
See PingOne's web app creation, OIDC settings, and client authentication methods.
OneLogin
- 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.
- On the app's Configuration tab, add Bird's callback to Redirect URIs.
- In Bird, enter
https://YOUR_SUBDOMAIN.onelogin.com/oidc/2as the issuer. The app's OpenID Provider Configuration Information link opens its discovery document. - 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. - Request
openid, plusprofileandemailas needed. OneLogin's discovery document advertises S256 PKCE andclient_secret_basicandclient_secret_postauthentication.
See OneLogin's OIDC application connection, provider configuration, and authorization request.
Salesforce
- In Salesforce Setup, create a local external client app and select Enable OAuth. Add Bird's callback under Callback URL.
- Allow
openid, plus the identity scopes forprofileandemailas needed. Enable Configure ID token and Include Standard Claims. The ID token audience must include the client ID you enter in Bird. - Select Require Secret for the Web Server Flow and Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows.
- In Bird, enter
https://login.salesforce.comas 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. - 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
- 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.
- 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. - 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. - Allow
openid. On the application's Scopes tab, enable the providedprofileandemailscopes 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
- Open Conversations and select an open conversation.
- Choose Request > Verification request, then Request authentication.
- 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.
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.
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.
{
"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"
}
}
}
}| Status | Meaning |
|---|---|
pending, processing | Sign-in is still in progress. These states do not produce outcome events. |
succeeded | Bird validated the provider's response and received confirmation from the originating Messages device. identity is present. |
cancelled | The customer or provider declined the sign-in. |
failed | Sending or provider validation failed, the device confirmation failed or did not arrive in time, or the callback was reused. Read failure_code. |
expired | Ten minutes passed without a result. |
superseded | A 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:
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 requiredambpermission. A404means the conversation or authentication request does not exist in this workspace. A422explains 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.
संबंधित संसाधन
इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।