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

# Authentication

> Authenticate with the Dialbird API using the OAuth 2.0 Authorization Code flow.

Every endpoint except `GET /health` requires an OAuth 2.0 **bearer access token**, obtained through the Authorization Code flow against Dialbird's OIDC provider. The token is a signed JWT with `aud: "public-api"`, which the API verifies against the issuer's JWKS.

## OAuth 2.0 endpoints

| Purpose         | URL                                          |
| --------------- | -------------------------------------------- |
| Authorization   | `https://app-staging.dialbird.io/oidc/auth`  |
| Token / Refresh | `https://app-staging.dialbird.io/oidc/token` |

The flow is **Authorization Code** (PKCE supported). After the user authorizes your client, exchange the authorization code at the token endpoint for an access token and refresh token.

## Sending the token

Send the access token as a bearer token on every request:

```bash theme={null}
curl https://app-staging.dialbird.io/api/v1/me \
  -H "Authorization: Bearer <access_token>"
```

<Warning>
  Access tokens must **never** be passed as a `?access_token=` query parameter. Requests that do are rejected with `401 invalid_token`.
</Warning>

## Scopes

Request only the scopes your integration needs. Each endpoint documents the scope it requires.

| Scope                | Grants                                                     |
| -------------------- | ---------------------------------------------------------- |
| `api:me`             | Read the authenticated business, user, and granted scopes. |
| `api:contacts:read`  | Read contacts.                                             |
| `api:contacts:write` | Create and update contacts.                                |
| `api:messages:read`  | Read messages.                                             |
| `api:messages:write` | Send messages.                                             |
| `api:calls:read`     | Read calls.                                                |
| `api:webhooks`       | Manage webhook subscriptions.                              |

A token missing the required scope for an endpoint receives `403 insufficient_scope`.

## Verifying a token

Call `GET /me` to confirm a token is valid and see what it resolves to. Zapier and other OAuth clients use this as their "Test Authentication" URL.

```bash theme={null}
curl https://app-staging.dialbird.io/api/v1/me \
  -H "Authorization: Bearer <access_token>"
```

```json theme={null}
{
  "business": { "id": "biz_123", "name": "Acme Co" },
  "user": { "id": "usr_456" },
  "client_id": "zapier",
  "scopes": ["api:me", "api:messages:write"]
}
```

## Token errors

| Status | Code                 | Meaning                                          |
| ------ | -------------------- | ------------------------------------------------ |
| `401`  | `missing_token`      | No `Authorization` header was sent.              |
| `401`  | `invalid_token`      | The token is malformed or failed verification.   |
| `401`  | `expired_token`      | The token is past its expiry — refresh it.       |
| `403`  | `insufficient_scope` | The token is valid but lacks the required scope. |
| `403`  | `business_suspended` | The business is suspended or not associated.     |

When a token is expired, use the refresh token against the token endpoint to obtain a new access token rather than re-running the full authorization flow.