Authentication
Use a workspace API key for your server or delegated OAuth for an agent connection.
API keys
Create a key in Integrations. Select the workspace and only the permissions your integration needs. The dashboard issues keys for 90 days and displays the secret once.
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 | Workspace, site, vertical catalog, and license requirements |
site:write | Site settings, drafts, and publication |
ads:read | Campaigns, advertising balance, and preparation jobs |
ads:write | Campaign preparation, launch, and pause |
leads:read | Leads, with the existing subscription contact masking |
metrics:read | Business performance and integration usage |
billing:read | Subscription status and invoices |
billing:write | Browser handoff to subscription checkout or billing management |
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 workspace 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, sees the requesting app and callback origin, chooses a workspace, and approves the requested permissions. 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.