Authentication

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:

curl https://app-staging.dialbird.io/api/v1/me \
  -H "Authorization: Bearer <access_token>"

Access tokens must never be passed as a ?access_token= query parameter. Requests that do are rejected with 401 invalid_token.

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.

curl https://app-staging.dialbird.io/api/v1/me \
  -H "Authorization: Bearer <access_token>"

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

Getting started

Concepts

OAuth 2.0 endpoints

Sending the token

Scopes

Verifying a token

Token errors

​OAuth 2.0 endpoints

​Sending the token

​Scopes

​Verifying a token

​Token errors

OAuth 2.0 endpoints

Sending the token

Scopes

Verifying a token

Token errors