Authentication

OAuth 2.0 — client_credentials

The API uses OAuth 2.0 with the client_credentials grant: your backend consumes your own workspace. There’s no user flow (authorization_code) for now.

curl -X POST https://api.apyconnect.io/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials

Credentials can go in Basic auth (recommended) or in the body (client_id/client_secret).

Opaque tokens

The access_token (at_live_… / at_test_…) is opaque: it’s not a JWT and carries no data. Verification is O(1) in the common case (cache) with immediate revocation. It lives ~1 h — when it expires, request another. Send it on every request:

Authorization: Bearer at_live_…

Test vs live mode

Each Application is test or live. Identifiers reflect it (ec_test_ / ec_live_, at_test_ / at_live_). Use it to separate integration from production.

Scopes

Permissions live on the Application, not on the token (the token inherits them as a snapshot). Check yours with GET /v1/me:

{ "object": "api_client_context", "workspace_id": "ws_…", "mode": "live",
  "scopes": ["contacts:read", "contacts:write", "messages:write"] }

Scope	Allows
`contacts:read` / `contacts:write`	Read / write contacts, tags, identifiers, custom fields
`conversations:read` / `conversations:write`	Read / manage conversations (status, assignment, priority)
`messages:read` / `messages:write`	Read / send messages
`channels:read` · `inboxes:read`	Read channels (with capabilities) and inboxes
`campaigns:read` / `campaigns:write`	Read / manage campaigns and their runs
`analytics:read`	Read the `/v1/analytics/*` reports
`webhooks:manage`	Manage webhook endpoints

If a token lacks the scope for an operation, the API responds 403 permission_error (insufficient_scope).

Rotation and revocation

Rotate the client_secret from the Application (the previous one stays valid for a grace period). Revoking the Application immediately invalidates all its live tokens.

Introduction

Reference

OAuth 2.0 — client_credentials

Opaque tokens

Test vs live mode

Scopes

Rotation and revocation

​OAuth 2.0 — client_credentials

​Opaque tokens

​Test vs live mode

​Scopes

​Rotation and revocation

OAuth 2.0 — client_credentials

Opaque tokens

Test vs live mode

Scopes

Rotation and revocation