Authentication
Use an API key for your server or delegated OAuth for an agent connection. Both cover all your businesses by default.
API keys
Create a key in Integrations. By default it covers all your businesses, including ones created later; you can pin it to one business instead. All eight permissions are selected by default; you can restrict them for a narrower integration. The dashboard issues keys for 90 days and displays the secret once.
With a key that covers several businesses, send the x-workspace header with the business ID (MCP: the business_id argument). Without it, a request fails with business_required and the list of businesses, unless the account has exactly one.
Authorization: Bearer bja_key_your_keyKeep credentials in a server secret store or the agent client's credential manager. Send them in the Authorization header. Revoke a key or agent connection in Integrations when it should stop working.
Scopes
| Scope | Access |
|---|---|
site:read | Businesses, overview, site, vertical catalog, and license requirements |
site:write | Business setup, service cities, site settings, drafts, and publication |
ads:read | Campaigns, money for ads, and preparation jobs |
ads:write | Ads launch and pause, campaign preparation |
leads:read | Leads, with contact details (never masked) |
metrics:read | Business performance and integration usage |
billing:read | Receipts for money added for ads |
billing:write | Browser handoff to the page where the owner adds money for ads |
A write scope does not replace a read scope. For example, an agent that prepares and monitors campaigns needs both ads:write and ads:read.
OAuth for agent clients
The authorization server supports public clients, dynamic registration, authorization code with PKCE S256, explicit owner consent, and resource indicators.
| Endpoint | Purpose |
|---|---|
/.well-known/oauth-authorization-server | Authorization server metadata |
/.well-known/oauth-protected-resource/mcp | MCP resource metadata |
/.well-known/oauth-protected-resource/v1 | REST resource metadata |
POST /oauth/register | Register HTTPS callbacks or HTTP loopback callbacks |
GET /oauth/authorize | Start the owner consent flow |
POST /oauth/token | Exchange a code or rotate a refresh token |
POST /oauth/revoke | Revoke the connection |
All paths above are relative to https://api.benjiads.com.
The owner signs in with their phone (a new number creates the account), sees the requesting app and callback origin, and approves the requested permissions. The connection covers all of the owner's businesses by default, including ones created later; the owner can pin it to one business. An account with no business yet can connect, and the agent then creates one with setup_business. When a client omits scope, the connection requests all eight supported scopes. An explicitly requested subset is respected. Existing connections keep their approved scopes; reconnect once to expand an older restricted grant. Authorization codes are single-use and expire after one minute once approved.
Use the exact resource in authorization and token requests:
- REST:
https://api.benjiads.com/v1 - MCP:
https://api.benjiads.com/mcp
An OAuth token issued for one resource cannot be used on the other. Personal API keys can use both interfaces.
Refresh and revocation
Access tokens last one hour. Refresh tokens rotate on every refresh and expire at the end of the original 30-day connection lifetime. Store each new refresh token before discarding the previous one. Reusing an old refresh token revokes the connection.
An expired, revoked, or invalid credential returns 401. Missing permissions return 403 with an OAuth challenge identifying the needed scope.