Create an embeddable ads connection session

POST /api/embed/ads-sessions

Returns a single-use URL to embed in an iframe: the end user logs in to Meta inside it and chooses which ad accounts to activate. The token in clear text is shown only once. On activation, Neike notifies by webhook (ads.connected) and the result is available through GET of the session. It requires that someone has accepted the Marketing terms: otherwise it answers 403 on creation, not inside the iframe. Requires the marketing:manage scope.

Request body

Field	Type		Description
`allowed_origins`	string[]	required	Origins allowed to embed the iframe. They feed the `frame-ancestors` of the CSP and the targetOrigin of the result postMessage. Up to 10. Example: `["https://app.tu-dominio.com"]`.
`external_ref`	string	optional	Business id in the client’s system. It comes back unchanged in the webhook and in the result, to correlate the accounts with their tenant. Example: `"tenant_8842"`.
`ttl_minutes`	number	optional	Validity of the session in minutes. Default: `30`.
`provider`	`meta`	optional	Ads provider. Today only `meta`; any other value answers 400 `unsupported_provider`. Default: `"meta"`.

Responses

Status	Description	Schema
`201`	—	EmbedAdsSessionCreatedDto
`400`	Invalid origins, ttl out of range or unsupported `provider`.	—
`403`	Nobody accepted the current version of the Marketing terms (`error: marketing_terms_not_accepted`).	—

Example

curl -X POST https://api.neike.dev/api/embed/ads-sessions \
  -H "x-neike-api-key: whk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
       "allowed_origins": [
         "https://app.tu-dominio.com"
       ]
     }'

EmbedAdsSessionCreatedDto

Field	Type		Description
`session_id`	string	required	Example: `"nkes_9fQ2aB…"`.
`token`	string	required	Session token. It is returned only once; only its SHA-256 is stored. Example: `"nkst_…"`.
`embed_url`	string	required	URL ready to embed in the iframe. Example: `"https://api.neike.dev/embed/ads?token=nkst_…"`.
`iframe_snippet`	string	required	`<iframe>` snippet ready to paste (sandbox included).
`provider`	`meta`	required	Example: `"meta"`.
`allowed_origins`	string[]	required	—
`external_ref`	string	optional	—
`expires_at`	string (date-time)	required	—
`status`	`pending`	required	Example: `"pending"`.