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)

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`
`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`, `get_launch_status`, `list_launch_drafts`, `get_launch_draft`
`copy:write`	`generate_ad_copy`
`creatives:write`	`generate_image`
`videos:write`	`generate_video`
`launches:write`	`create_launch_draft`, `delete_launch_draft`

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

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.
create_launch_draft never publishes ads — launching real campaigns (spend) stays a human action in the dashboard.
Revoke API keys anytime (DELETE /api/settings/api-keys/<id>?teamId=...); OAuth grants expire with their refresh tokens.

​OAuth 2.1

​API keys

​Scopes

​Use the credential

​Rate limits

​Security notes