AppExchange / MC App API Auth Flow (Draft) ┌─┐ ║"│ └┬┘ ┌┼┐ ┌───────┐ │ ┌──┐ │Partner│ ┌┴┐ │MC│ │Webapp │ Marketer └──┘ └───┬───┘ │ ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ │AppExchange Setup │ │ │Must select offline access scope in Marketing Cloud Installed Packages │ │ │to use tokens after the user logs out. │ │ └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ┌┴┐ 𝟏 Initiate Partner App Load in MC │ │ │ │ ───────────────────────────────────────────────────────────────> │ │ │ │ │ │ │ │ 𝟐 Load webapp which is iframed in. ┌┴┐ │ │ │ ────────────────────────────────────────────────────────────────────────────────────────────────────────────> │ │ │ │ │ │ │ │ │ │ │ │ ╔════════════╪═╪══════════════╤═════════════════════════════════════════════════╪═══════════════════════════════════════════════════════════════════════════════════════════════════════════════╪═╪═════════════════════════════════════════════════╗ ║ UI AUTHORIZATION CODE FLOW │ │ │ │ ║ ╟─────────────────────────────┘ 𝟑 Redirect end user │ │ ║ ║ │ │ 302 v2/authorize?response_type=code&client_id=&redirect_uri=&scope=&state= │ │ ║ ║ │ │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │ ║ ║ │ │ │ │ │ ║ ║ │ │ 𝟒 GET v2/authorize?response_type=code │ │ │ ║ ║ │ │ &client_id=&redirect_uri=&scope=&state= │ │ │ ║ ║ │ │ ───────────────────────────────────────────────────────────────> │ │ ║ ║ │ │ │ │ │ ║ ║ │ │ │────┐ │ ║ ║ │ │ │ │ 𝟓 Marketing Cloud authorization service redirects the user’s web browser to the Marketing Cloud login page │ ║ ║ │ │ │<───┘ │ ║ ║ │ │ │ │ │ ║ ║ │ │ │────┐ │ │ ║ ║ │ │ │ │ 𝟔 User logs in to Marketing Cloud. │ │ ║ ║ │ │ │<───┘ │ │ ║ ║ │ │ │ │ │ ║ ║ │ │ 𝟕 Redirect w/authorization. 302 redirect_uri?state=&tssd=&code=│ │ │ ║ ║ │ │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │ ║ ║ │ │ │ │ │ ║ ║ │ │ │ │ │ ╔═════════════════════════════════════╗ ║ ║ │ │ │ 𝟖 GET redirect_uri?state=&tssd=&code= │ │ ║Authorization code on behalf of the ░║ ║ ║ │ │ ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────> │ │ ║end user good for 5 minutes. Must ║ ║ ║ │ │ │ │ │ ║be exchanged for access tokens. ║ ║ ╚════════════╪═╪════════════════════════════════════════════════════════════════╪═══════════════════════════════════════════════════════════════════════════════════════════════════════════════╪═╪══╚═════════════════════════════════════╝════════╝ │ │ │ │ │ │ │ │ │ │ │ │ ╔══════════╪═════════╤═════════════════════════════════════════════════════════════════════════════════════════════════════╪═╪═══════════════════════════════════════════════════════════════════════╗ │ │ ║ ACCESS TOKEN FLOW │ │ │ ║ │ │ ╟────────────────────┘ 𝟗 POST TSSD/v2/token │ │ ║ │ │ ║ │ │ authorization code, client_id, client_secret, redirect_uri, offline scope, and account_id. │ │ ║ │ │ ║ │ │ <───────────────────────────────────────────────────────────────────────────────────────────────────────────│ │ ║ │ │ ║ └┬┘ │ │ ║ │ │ ║ │ 𝟏𝟎 access_token(20m), refresh_token(30d), rest_instance_url, and soap_instance_url. │ │ ╔══════════════════════════════════════╗ ║ │ │ ║ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─> │ │ ║The same client_id and ░║ ║ │ │ ║ │ │ │ ║client_secret is used in all stacks. ║ ║ │ │ ║ │ │ │ ╚══════════════════════════════════════╝ ║ │ │ ║ │ │ │────┐ ║ │ │ ║ │ │ │ │ 𝟏𝟏 Stores TSSD urls and refresh_token which expire in 30 days. ║ │ │ ║ │ │ │<───┘ ║ │ │ ╚══════════╪═══════════════════════════════════════════════════════════════════════════════════════════════════════════════╪═╪═══════════════════════════════════════════════════════════════════════╝ │ │ │ │ │ │ │ │ 𝟏𝟐 User interacts with partner APP. │┌┴┐ │ │ ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────>│ │ │ │ │ │└┬┘ │ │ │ 𝟏𝟑 │ │ │ │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ╔══════════╪═════════════════╤═════════════════════════════════════════════════════════════════════════════════════════════╪═╪═══════════╗ │ │ ║ APP ACCESSES MC RESOURCES │ │ │ ║ │ │ ╟────────────────────────────┘ 𝟏𝟒 FUEL API │ │ ║ │ │ ║ │ │ Authorization: Bearer {Access Token} │ │ ║ │ │ ║ │ │ POST TSSD/route/todo │ │ ║ │ │ ║ │ │ JSON Payload │ │ ║ │ │ ║ │ │ <───────────────────────────────────────────────────────────────────────────────────────────────────────────│ │ ║ │ │ ║ │ │ │ │ ║ │ │ ║ │ │────┐ │ │ ║ │ │ ║ │ │ │ 𝟏𝟓 MID & AppID from Auth Principal │ │ ║ │ │ ║ │ │<───┘ │ │ ║ │ │ ║ └┬┘ │ │ ║ │ │ ║ │ 𝟏𝟔 │ │ ║ │ │ ║ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─> │ │ ║ │ │ ╚══════════╪═══════════════════════════════════════════════════════════════════════════════════════════════════════════════╪═╪═══════════╝ └┬┘ │ └┬┘ │ │ 𝟏𝟕 Logout │ ╔══════════════════════════════════════╗ │ ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────>│ ║access_token is immediately revoked. ░║ │ │ │ ╚══════════════════════════════════════╝ │ │ │ │ │ │ │ │ │ │ │ │ . . . . . ╔═════════════════════════════╗ . ═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣ Background Partner Processes╠═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════ . . ╚═════════════════════════════╝ . │ │ │ │ │ │ │ ╔═══════╤════════════╪════════════════════════════════════════════════════════════════════════════════════════════════════════════════╪══════════════════════════════════════════════════════════════════════════════╗ │ ║ LOOP │ Periodically:Daily/Weekly │ ────┐ ║ │ ╟───────┘ │ │ │ 𝟏𝟖 Daily process to check for seed list changes in each account. ║ │ ║ │ │ <───┘ ║ │ ║ │ │ ║ │ ║ │ │ ║ │ ║ │ │ ║ │ ║ │ │ ║ │ ║ ╔══════════╪══════════╤═════════════════════════════════════════════════════════════════════════════════════════════════════╪══════════════════════════════════════════════════════════╗ ║ │ ║ ║ REFRESH TOKEN FLOW │ │ ║ ║ │ ║ ╟─────────────────────┘ ────┐ ║ ║ │ ║ ║ │ ┌ │ 𝟏𝟗 Retrieves TSSD urls and refresh_token ║ ║ │ ║ ║ │ │<───┘ ║ ║ │ ║ ║ │ │ │ ║ ║ │ ║ ║ ┌┴┐ 𝟐𝟎 POST TSSD/v2/token │ │ ║ ║ │ ║ ║ │ │ <───────────────────────────────────────────────────────────────────────────────────────────────────────────│ │ ║ ║ │ ║ ║ └┬┘ │ │ ║ ║ │ ║ ║ │ 𝟐𝟏 access_token(20m), refresh_token(30d) │ │ ║ ║ │ ║ ║ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─> │ │ ║ ║ │ ║ ║ │ │ │ ║ ║ │ ║ ║ │ │ │────┐ ║ ║ │ ║ ║ │ │ │ │ 𝟐𝟐 Stores refresh_token which expire in 30 days. ║ ║ │ ║ ║ │ │ │<───┘ ║ ║ │ ║ ╚══════════╪═══════════════════════════════════════════════════════════════════════════════════════════════════════════════╪═╪═════════════════════════════════════════════════════════╝ ║ │ ║ │ │ │ ║ │ ║ ┌┴┐ 𝟐𝟑 FUEL API │ │ ║ │ ║ │ │ Authroziation: Bearer {Access Token} │ │ ║ │ ║ │ │ POST /route/todo │ │ ║ │ ║ │ │ JSON Payload │ │ ║ │ ║ │ │ <───────────────────────────────────────────────────────────────────────────────────────────────────────────│ │ ║ │ ║ │ │ │ │ ║ │ ║ │ │────┐ │ │ ║ │ ║ │ │ │ 𝟐𝟒 MID & AppID from Auth Principal │ │ ║ │ ║ │ │<───┘ │ │ ║ │ ║ └┬┘ │ │ ║ │ ║ │ 𝟐𝟓 │ │ ║ │ ║ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─> │ │ ║ │ ╚════════════════════╪═══════════════════════════════════════════════════════════════════════════════════════════════════════════════╪═╪═════════════════════════════════════════════════════════════════════════════╝ Marketer ┌──┐ ┌──│ │──┐ ┌─┐ │MC│ │Pa│ │er│ ║"│ └──┘ │We│ │p │ └┬┘ └──│ │──┘ ┌┼┐ │ │ │ │ │ ┌┴┐ │ │ └┬┘