---
title: "Request conversation authentication"
canonical: "https://bird.com/docs/api/reference/create-amb-authentication"
---

# Request conversation authentication

`POST /v1/amb/conversations/{conversation_id}/authentications`

Sends a native sign-in request to an open conversation whose device advertises `AUTH2`. The business needs an enabled authentication provider. The request expires after ten minutes. Bird validates the provider's response and waits for confirmation from the originating Messages device before storing the verified identity with the conversation. The customer's tokens are never stored or returned. A new request supersedes an unfinished one in the same conversation, including when the new request then fails to send. Reusing an idempotency key returns the original request. The outcome arrives as a webhook event. Read the request to recover a missing event.

## Servers

- `https://{region}.platform.bird.com`: Regional API endpoint. Use the host for the region your organization is hosted in. Official Bird SDKs and the CLI select it automatically from your API key, so you rarely need to set it by hand.
  - `region`: `us1`, `eu1`. Default: `us1`. The region your organization's data is hosted in.

## Authentication

Use one authentication option:

- `BearerAuth`: HTTP bearer authentication. Pass the API key as a bearer token in the `Authorization` header. Workspace
keys use `bk_{region}_*`; organization master keys use `bm_{region}_*`.
The prefix identifies the region and selects the
API endpoint. Official Bird SDKs and the CLI derive the region from the key.

## Code samples

**cURL**

```sh
curl -X POST "https://us1.platform.bird.com/v1/amb/conversations/{conversation_id}/authentications" \
  -H "Authorization: Bearer $TOKEN"
```

Examples: [cURL](/docs/api/reference/create-amb-authentication.curl.md)

## Example response `202`

```json
{
  "id": "amauth_01krdgeqcxet5s7t44vh8rt9mg",
  "conversation_id": "acv_01krdgeqcxet5s7t44vh8rt9mg",
  "provider_id": "aauthp_01krdgeqcxet5s7t44vh8rt9mg",
  "message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
  "status": "pending"
}
```

## Path parameters

- `conversation_id` (string, required): Conversation identifier. Starts with `acv_`.

## Header parameters

- `X-Workspace-Id` (string, optional): Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.
- `Idempotency-Key` (string, optional)

  Client-supplied key. On operations supporting request deduplication, a retained
  response is replayed for duplicate requests with the same key within the
  idempotency window (3 hours by default). This protection requires a workspace,
  organization, or staff-account scope. User-only and unscoped unauthenticated operations,
  streams, and operations with a separate replay contract do not use this
  response replay.

  On a supported operation, if idempotency protection is unavailable before execution, the API returns
  `503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with
  backoff using the same key and request. An operation that takes effect before
  its response is retained can still execute again on retry.

  Two distinct 409 errors signal misuse:

  - `request_in_progress` (E01004): The same key is currently being
    processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  - `idempotency_key_reuse` (E01005): The same key has already completed
    against a different request body or method. Generate a new key.

  Recommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).
- `X-Organization-Id` (string, optional): Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

## Response body

- `id` (string, required)
- `conversation_id` (string, required)
- `provider_id` (string, required)
- `provider_revision` (integer, required): Provider revision used by this attempt.
- `message_id` (nullable string, required): Authentication message reference, or null before acceptance.
- `status` (string, required)

  Progress of an authentication request. Every value except `pending` and `processing` is terminal.

  - `pending`: the sign-in message was accepted and the customer has not finished.
  - `processing`: the authorization code is being exchanged or Bird is waiting for confirmation from the originating Messages device.
  - `succeeded`: the identity was validated and the originating Messages device confirmed sign-in.
  - `failed`: delivery, identity verification or device confirmation failed, or the provider callback was replayed.
  - `cancelled`: the customer or the provider declined authorization.
  - `expired`: the request passed its ten-minute lifetime.
  - `superseded`: a newer request, or a change to the conversation, business or provider, replaced the request.

  Possible values: `pending`, `processing`, `succeeded`, `failed`, `cancelled`, `expired`, `superseded`
- `created_at` (string, required): When the attempt was created.
- `expires_at` (string, required): When this attempt expires.
- `completed_at` (string): When the attempt reached a terminal outcome.
- `failure_code` (string)

  Why the request did not succeed. Contains no provider response or credentials.

  - `authentication_expired`: ten minutes passed. Request a new sign-in.
  - `new_authentication`: a newer request replaced this one.
  - `conversation_closed` and `conversation_changed`: the conversation closed or reopened. Wait for the customer to write again.
  - `configuration_changed`: the provider settings changed or the business was disconnected.
  - `user_cancelled`, `apple_authentication_cancel`: the customer declined.
  - `provider_rejected`, `token_exchange_failed`, `identity_verification_failed`: the provider response could not be accepted. Check the provider settings, then request a new sign-in.
  - `processing_interrupted`: the exchange or device confirmation did not finish within one minute. Ask the customer to sign in again and return to Messages.
  - `apple_authentication_failure`: the Messages device reported a failed sign-in. Request a new sign-in.
  - `authentication_replayed`: the provider callback was used more than once. Request a new sign-in.
  - `message_submission_failed`, `message_failed`: the sign-in message could not be sent.

  Other values are message delivery reasons passed through unchanged.
- `identity` (object): Validated identity claims. Verification does not create a persistent login session or grant access to customer systems.
- `identity.issuer` (string, required): Issuer that verified the identity.
- `identity.subject` (string, required): Provider-issued user identifier. Not necessarily your CRM customer ID.
- `identity.name` (string): Name supplied by the provider when name collection is enabled.
- `identity.email` (string): Email supplied by the provider when email collection is enabled.
- `identity.email_verified` (boolean): Whether the provider verified this email address.
- `identity.authenticated_at` (string): When the provider says the user authenticated. May precede this verification.
- `identity.verified_at` (string, required): When Bird completed identity validation and confirmed the originating Messages conversation.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)
