Authentication - AdStellar

The AdStellar MCP server and REST API support two credentials:

OAuth 2.1 (recommended for interactive MCP clients like Claude and ChatGPT)
API keys (recommended for your own agents and scripts)

Both resolve to the same team + scopes; every tool runs as your team with full tenant isolation.

OAuth 2.1

MCP-aware clients walk the flow automatically the first time they connect to https://app.adstellar.ai/api/mcp:

The server answers 401 with a WWW-Authenticate header pointing at the discovery metadata (/.well-known/oauth-protected-resource).
The client registers itself via Dynamic Client Registration (RFC 7591) at /api/oauth/register.
You’re redirected to the AdStellar consent screen: pick the team and the scopes to grant.
The client exchanges the resulting code for an access + refresh token pair (PKCE, S256-only) at /api/oauth/token.

Access tokens live 1 hour; refresh tokens 30 days and rotate on every use. Nothing needs to be configured by hand — just paste the MCP URL into your client. Endpoints:

Endpoint	Purpose
`GET /.well-known/oauth-authorization-server`	Discovery metadata (RFC 8414)
`POST /api/oauth/register`	Dynamic client registration (RFC 7591)
`GET /api/oauth/authorize`	Consent screen (requires AdStellar login)
`POST /api/oauth/token`	Code exchange + refresh rotation (PKCE)

OpenID Connect

The authorization server is also an OpenID Connect provider, so clients that need a verified identity (for example ChatGPT Enterprise domain restrictions) can request the openid and email scopes alongside the tool scopes.

Discovery: https://app.adstellar.ai/.well-known/openid-configuration
Signing keys: https://app.adstellar.ai/.well-known/jwks.json (RS256)
UserInfo: GET https://app.adstellar.ai/api/oauth/userinfo with the access token as a Bearer header

When openid is granted, the token response includes an id_token with sub, aud, iss, exp, iat, the request nonce if one was sent, and, with the email scope, email and email_verified: true. Every AdStellar account has a verified email, so the claim is always true. The openid and email scopes grant no tool access and are not available for API keys.

API keys

For unattended agents, create a team-scoped key (ast_live_...) in Settings → Developers or via the management API (owner/admin):

curl -X POST https://app.adstellar.ai/api/settings/api-keys \
  -H "Content-Type: application/json" \
  -H "Cookie: <your session>" \
  -d '{
    "teamId": "<your team id>",
    "name": "my-agent",
    "scopes": ["org:read", "models:read", "analytics:read", "assets:read", "campaigns:read", "copy:write", "creatives:write", "videos:write"]
  }'

The plaintext key is returned exactly once — only its SHA-256 hash is stored.

Scopes

Scope	Unlocks
`org:read`	`get_team_info`, `get_credit_balance`, `get_brand_kit`, `list_products`, `list_projects`, `list_ad_accounts`
`org:write`	`create_workspace`, `create_brand_kit_from_url`, `create_product_from_url`
`models:read`	`list_models`, `list_avatars`, `list_voices`
`analytics:read`	`query_performance`
`assets:read`	`search_assets`, `lookup_asset`, `get_generation_status`
`campaigns:read`	`list_campaigns`, `lookup_campaign`, `get_launch_status`, `list_launch_drafts`, `get_launch_draft`, `get_launch_options`, `get_campaign_build`
`copy:write`	`generate_ad_copy`
`creatives:write`	`generate_image`
`videos:write`	`generate_video`
`launches:write`	`create_launch_draft`, `delete_launch_draft`
`campaigns:write`	`pause_campaign`, `resume_campaign`, `archive_campaign`, `update_campaign_budget`, `pause_ad_set`, `resume_ad_set`, `update_ad_set_budget`, `pause_ad`, `resume_ad`
`launches:publish`	`build_campaign`, `launch_campaign` (spends credits and ad budget)
`automations:read`	`get_automation_rule_schema`, `list_automation_rules`, `preview_automation_rule`, `list_pending_automation_actions`
`automations:write`	`create_automation_rule`, `set_automation_rule_active`, `approve_automation_action`, `reject_automation_action`

Tools you don’t have the scope for are hidden from tools/list and rejected with a clear error.

Use the credential

Authorization: Bearer ast_live_...   # API key
Authorization: Bearer ast_at_...     # OAuth access token

Discovery needs no credential: initialize, ping and tools/list answer unauthenticated so a client can read every tool and its securitySchemes before linking an account. With a credential, tools/list narrows to the tools that credential’s scopes allow. tools/call always requires one.

Rate limits

120 requests per minute per credential, per endpoint. 429 responses include a Retry-After header.

Security notes

Keys and tokens are never logged; only hashes are stored.
Generation tools deduct credits from your team’s balance exactly as if you’d run them in the app.
Every tool that changes a live ad, spends credits, or creates a rule is two-step: called without confirmationToken it returns a preview plus a short-lived token (10 minutes, bound to the credential, tool and exact arguments); the change only happens when the tool is called again with that token. Agents must show the preview and get explicit approval in between.
launch_campaign publishes paused by default; pass status: "active" to start delivery immediately. It costs the same AI credits as launching in the app.
Write scopes can only be granted by team owners/admins on the consent screen.
Revoke API keys anytime (DELETE /api/settings/api-keys/<id>?teamId=...); OAuth grants expire with their refresh tokens.

​OAuth 2.1

​OpenID Connect

​API keys

​Scopes

​Use the credential

​Rate limits

​Security notes