Connector

Authentication

A remote client authenticates with OAuth 2.1 and holds its own token. A script authenticates with an API key. Both reach the same tools; only the remote path supports per-user grants and revocation.

The OAuth flow

Nothing is provisioned by hand. A client discovers the server, registers itself, and sends the person to a consent screen. Every URL below is live and can be called by a reviewer without an account.

1. Discover the resource

Protected resource metadata

curl https://cresva.ai/.well-known/oauth-protected-resource/mcp {  "resource": "https://cresva.ai/mcp",  "authorization_servers": ["https://cresva.ai"],  "scopes_supported": ["read:marketing", "read:commerce", "write:negotiation"],  "bearer_methods_supported": ["header"]}

RFC 9728. authorization_servers points at the document below.

A client that calls /mcp without a token gets the same pointer in the challenge, so discovery works from either direction.

Challenge

HTTP/2 401www-authenticate: Bearer resource_metadata="https://cresva.ai/.well-known/oauth-protected-resource/mcp",  error="invalid_token",  error_description="This connector needs a Cresva access token."

2. Register

Dynamic client registration, RFC 7591. It is open by design, because a client registers before it has any credential. Registering grants nothing: no consent, no data, no access to an account.

curl -X POST https://cresva.ai/api/oauth/register \  -H 'content-type: application/json' \  -d '{    "client_name": "Your client",    "redirect_uris": ["https://your.app/callback"],    "grant_types": ["authorization_code", "refresh_token"],    "response_types": ["code"],    "token_endpoint_auth_method": "none"  }'

Redirect URIs are matched exactly

https, http on loopback, or an application's own private-use URI scheme per RFC 8252. They are recorded verbatim and compared character for character at authorisation time, so a client cannot broaden one after the fact. Validation is all or nothing across the array: one unacceptable entry refuses the whole registration.

3. Authorise

PKCE is mandatory and S256 is the only accepted method. The resource parameter is required and must name the resource from the discovery document, per RFC 8707.

Authorize

https://cresva.ai/oauth/authorize  ?response_type=code  &client_id=<from registration>  &redirect_uri=<exactly what you registered>  &code_challenge=<S256 of your verifier>  &code_challenge_method=S256  &scope=read:marketing read:commerce  &state=<opaque>  &resource=https://cresva.ai/mcp

Scopes, in plain words

read:marketing

Read your ad performance. Spend, ROAS, campaigns, anomalies, forecasts, budgets and profit for the brands you choose. Read only. 13 tools. Granted unless the person clears it.

read:commerce

Read your public storefront. Products, prices, trust signals and the catalogue an AI shopper already sees. This information is public. 7 tools. Granted unless the person clears it.

write:negotiation

Negotiate prices on your behalf. Open real price negotiations on your storefront. A negotiation can end in an accepted order at a discount, so this one changes things rather than reading them. 1 tool. OFF by default. The person has to turn it on.

write:proposals

Propose changes for you to approve. Put a suggested change into your approvals queue, where you read it and decide. It cannot approve anything, and it cannot change an ad account: approving and running both stay in your dashboard. 1 tool. OFF by default. The person has to turn it on.

API keys, the alternative

The local package and any direct HTTP caller authenticate with a Cresva API key instead. A key is not tied to a person, so it has no consent screen, no grant row and nothing to revoke from Connected apps: you rotate the key.

With a key

curl -X POST https://cresva.ai/api/mcp/brands \  -H 'authorization: Bearer sk_live_...' \  -H 'content-type: application/json' \  -d '{}'

TEST and LIVE

sk_live_ reads your real connected accounts.
sk_test_ reads simulated data. Nothing it returns is your account, and nothing it does can change one. Use it in CI and in demos.

See Test mode for what the simulated data contains.

Tokens rotate

Refresh tokens are single use. A refresh returns a new refresh token and invalidates the one you sent; replaying a consumed token revokes the grant. A client that keeps reusing one will be disconnected, which is the intended outcome for a leaked token.

The OAuth flow#