Subscribe API Flow
Guide the user through subscribing an Adobe API to a credential in their workspace, step by step.
Before starting: invoke the dev-console-context skill.
Steps
Get org — Call
get_organisationsand ask the user which org to use.New or existing project? — Ask the user:
1. Create a new project 2. Use an existing projectIf new project (1):
- Ask the user for a title only (e.g. "My Analytics Project"). Do NOT ask for a name.
- Derive the
namefrom the title automatically: strip all non-alphanumeric characters, camelCase or concatenate words, truncate to 20 characters. For example: "My Analytics Project" → "MyAnalyticsProject". - Call
create_projectwithprojectType: "default", the derivedname, and the user's title. - The response returns both
projectIdandworkspaceIddirectly — the default workspace is always Production. Do NOT calllist_workspacesunless the credential type is User Auth (AdobeId), in which case calllist_workspacesto confirm the available workspaces.
If existing project (2):
- Ask:
1. All projects 2. My projects (created or modified by me)- 1 → call
get_projectswithfilterBy: "all" - 2 → call
get_projectswithfilterBy: "me"
- 1 → call
- Show the returned project list as a numbered list (names only, no raw IDs) and ask the user which project they want.
- Call
list_workspaceswith the chosen project → show workspace list as a numbered list → ask which workspace to use. - Once the workspace is selected, automatically (without asking):
- Call
get_credentialsfor that workspace. - For each credential in the response, call
get_credential_serviceswith itsid_integration. Only show credentials returned byget_credentials— do NOT include org-level credentials. - Display a summary like:
IfHere's what's already set up in this workspace: 📋 Credential: "My S2S Cred" (OAuth Server-to-Server) APIs subscribed: Adobe Analytics, Firefly API 📋 Credential: "My Web App" (AdobeId) APIs subscribed: noneget_credentialsreturns an empty list, say: "No credentials found in this workspace yet." - Then proceed to ask which API they want to add.
- Call
Find the API — If the user asks "what APIs are available", "show me available APIs", or similar, call
list_serviceswithfilterBy: "enabled"and display only the enabled APIs as a list (name + description, no raw codes). If the user named a specific API, calllist_serviceswithfilterBy: "enabled"to find itscodeand full details. Never guess an SDK code.Pick credential type — Always run this step based on the API's supported types — never skip it because an existing credential was found. An API can have multiple enabled instances with different
typevalues. Collect ALL enabled instances for the API code, then:- Any instance whose
typeisadmin_entp→ do not offer it as a selectable option, but show a note to the user:⚠️ Admin Enterprise credential is also available for this API but is not yet supported in this connector. You can still subscribe to it via the Adobe Developer Console. - If no instances remain after setting aside
admin_entp→ tell the user:
and stop.This API only supports Admin Enterprise credentials, which are not yet supported in this connector. You can subscribe via the Adobe Developer Console directly. - If only one remaining credential type → proceed with it automatically.
- If multiple remaining credential types → show them as a numbered list and ask: "This API supports multiple credential types. Which would you like to use?"
- Analytics credential (internal:
analytics) — if ananalyticsinstance is present - User Auth (AdobeId) — for user-facing apps (internal:
adobeid) - OAuth Server-to-Server — for server-to-server access (internal:
oauth_server_to_server, also used forentp)
- Analytics credential (internal:
- Wait for the user to pick before proceeding. Do not auto-select based on what credentials already exist in the workspace.
- Show only credential type names in this list — never mention existing credentials here. Do not append "subscribe to the existing X credential" or any reference to existing workspace credentials. Existing credential lookup happens in step 6, after the type is chosen.
- Any instance whose
Check for product profiles — After the credential type is decided, inspect its
properties.licenseConfigsarray from the matching API instance:- If it is non-empty: present the profiles as a numbered list (show
name, never rawidorproductId) and tell the user: "You can select one or more of these profiles." Collect their choices — you'll need the selected profiles'idandproductIdfields when subscribing. - If it is empty or absent: skip directly to step 6 with no
licenseConfigs. - This step must complete before any credential creation or subscription call — even when creating a new credential. Never pass
servicestocreate_oauth_s2s_credentialuntillicenseConfigshave been resolved.
- If it is non-empty: present the profiles as a numbered list (show
Subscribe — All credentials are workspace-scoped, so always use the workspace-level tools:
OAuth Server-to-Server credential (
oauth_server_to_server) → callsubscribe_credential_to_services:- Pass
orgId,projectId,workspaceId,credentialType: "oauth_server_to_server",credentialId, andservices. - Each service entry must include
licenseConfigsif the user selected product profiles in step 5. An emptylicenseConfigs: []is NOT the same as omitting it — pass the user's selections. - The
credentialTypemust always match the credential's actual type (oauth_server_to_server), never the API's type (entp).
All credential types use
subscribe_credential_to_services(PUT). The server automatically preserves all already-subscribed services — only pass the service(s) you want to add or change; do NOT pre-fetch and re-send the full existing list. Preservation is per-service, not per-licenseConfig: if you're adding a licenseConfig to an already-subscribed service, include that service's full intended licenseConfigs list (existing plus new), not just the new one.- Pass
Report success — If
subscribe_credential_to_servicesreturns a 200, report success immediately without a separate verification call: "✓ [API name] has been successfully subscribed to your [credential type] credential." List all currently subscribed APIs from the services array you sent (no need to re-fetch). Only callget_credential_servicesif the response is ambiguous or an error was returned.
Unsubscribe API Flow
Trigger when the user wants to remove an API from a credential — phrases like "unsubscribe X", "remove Analytics from this credential", "stop using Firefly API", "disconnect this API".
- If org/project/workspace/credential context isn't already established, run Step 1–2 of the flow above to get there, then call
get_credentials+get_credential_services(per the pairing rule) to show the user which credentials exist and what's subscribed to each. - Ask the user which credential and which subscribed API(s) they want to remove — show names, never raw IDs or SDK codes.
- Tell the user exactly what is about to be removed — the API name(s), the credential, and the project, by name (never raw IDs or SDK codes) — and that it can't be undone. Do not ask them to type the project title or any other name. The client shows its own Yes / No approval prompt when you call the tool; that prompt is the confirmation.
- Call
unsubscribe_credential_from_servicewithorgId,projectId,workspaceId,credentialType,credentialId, andsdkCodes(the codes to remove). This is the only tool used for unsubscribing, for every credential type. If the user declines the approval prompt, stop — do not retry or work around it — and ask what they would like to do instead.- Never build this manually by re-PUTting a reduced service list via
subscribe_credential_to_services. Always useunsubscribe_credential_from_service. - For
oauth_server_to_servercredentials specifically, this tool internally calls the dedicated Console unsubscribe endpoint (unsubscribe_oauths2s_to_service) once persdkCode, instead of the fetch-then-resubscribe path used for other credential types. You don't call that endpoint directly — always go throughunsubscribe_credential_from_service; it selects the right path automatically based oncredentialType.
- Never build this manually by re-PUTting a reduced service list via
- Report success: "✓ [API name] has been removed from your [credential type] credential." List the
remainingAPIs from the tool's response — no need to re-fetch.
Credential creation inputs
When no credential exists and one must be created, never ask the user for a name or description — derive them automatically using the pattern {projectName}-{type}[-{subtype}]:
| Credential type | Platform / subtype | Auto-generated name example |
|---|---|---|
| OAuth S2S | — | mcptesting-s2s |
| AdobeId | WebApp | mcptesting-adobeid-webApp |
| AdobeId | SinglePageApp | mcptesting-adobeid-singlePageApp |
| AdobeId | NativeApp | mcptesting-adobeid-native |
| AdobeId | apiKey | mcptesting-adobeid-apikey |
| Analytics | Web | mcptesting-analytics-web |
| Analytics | iOS | mcptesting-analytics-ios |
| Analytics | Android | mcptesting-analytics-android |
Set description to: "{Type} credential for {projectTitle}" (e.g. "OAuth S2S credential for mcptesting").
Truncate the name to 50 characters if needed. Use lowercase and hyphens only.
OAuth Server-to-Server (create_oauth_s2s_credential)
- Auto-generate name and description. No further input needed — proceed directly to creation.
- Never pass
servicestocreate_oauth_s2s_credential— always create the credential first (noservices), then subscribe in a separatesubscribe_credential_to_servicescall. Inline service attachment is unreliable and causes confusing retry flows.
User Auth — AdobeId (create_user_auth_credential)
- Auto-generate name and description.
- Ask only for platform. Present only platforms the API supports (from its
platformList) as a numbered list:1. WebApp — web application 2. SinglePageApp — SPA/React/Angular app 3. NativeApp — desktop or mobile app 4. apiKey — server-side API key access
Before asking for platform, if available_scopes is present:
- Display a table of available scopes and tell the user: "All scopes are granted by default and cannot be deselected."
Platform-specific inputs — NEVER invent placeholder values, always wait for the user:
WebApp/SinglePageApp: ask for both:defaultRedirectUri— plain URL (e.g.https://example.com/callback)redirectUriList— one or more redirect URI patterns; pass as plain URLs, the server escapes dots automatically
NativeApp: no extra inputs required — proceed directly.apiKey: ask fordomain. No redirect URI needed.
Analytics (create_analytics_credential)
- Auto-generate name and description.
- Ask only for platform as a numbered list:
1. Web — web app 2. iOS — iOS mobile app 3. Android — Android mobile app
Platform-specific inputs — NEVER invent placeholder values:
Web: ask for both:defaultRedirectUri— plain URL (e.g.https://example.com/callback)redirectUriList— one or more redirect URI patterns; pass as plain URLs, the server escapes dots automatically
iOS: ask forurlScheme. No redirect URI needed.Android: no extra inputs required — proceed directly.
After creating any credential, use its returned id as credentialId in the subscription call. Never re-fetch credentials after a fresh creation.
Whenever any tool response includes a console_url field (project creation, credential creation, subscription), always display it to the user as a clickable link:
🔗 View in Adobe Developer Console: {console_url}
When Instructions Are Unclear
If you're unsure about an API, credential type, product profile, or Adobe concept during this flow — call search_adobe_docs before asking the user to clarify. For example:
- User asks to subscribe an API you don't recognise → search "Adobe {API name} API developer documentation"
- Unclear what scopes or product profiles an API requires → search "Adobe {API name} OAuth scopes product profile"
- Unsure which credential type fits the user's use case → search "Adobe Developer Console credential types OAuth S2S user auth"
Always prefer fetching from official docs over guessing.
Rules
- Do not assume anything not explicitly described in this skill — if a behavior, field, or API detail is unclear or not covered here, call
search_adobe_docsto look it up in official Adobe documentation before proceeding. entpAPIs (e.g. Adobe Campaign) use an OAuth S2S credential. Never show "entp" to the user.admin_entpinstances are never selectable — always show a "coming soon" note with a link to the Console, but never block the rest of the flow. Only stop entirely if ALL instances areadmin_entp.- Always use the API
typefield to determine credential type. Completely ignoreoauthServerToServerOnly. Mapping:adobeid→create_user_auth_credential,analytics→create_analytics_credential,entp→create_oauth_s2s_credential,oauth_server_to_server→create_oauth_s2s_credential. - Never skip step 4. Credential type must be chosen based on the API's supported types every time — not inferred from what credentials already exist in the workspace.
- Always pair
get_credentialswithget_credential_services. Wheneverget_credentialsis called, immediately follow up by callingget_credential_servicesfor each credential returned before presenting anything to the user. Never show credentials without their subscribed APIs. - Never show raw IDs (licenseConfigId, credentialId, productId) to the user — use names instead.
- Integrations and credentials are the same concept. The
get_credentialsresponse usesid_integrationas the credential ID — use this value wherevercredentialIdis required in any tool call.integration_nameis the credential's display name. - Never use internal jargon — present
licenseConfigsas "product profiles" to the user. - Never skip product profile selection. If
properties.licenseConfigsis non-empty for an API, always complete step 5 and include the selectedlicenseConfigsin theservicesarray — both when subscribing to an existing credential and when creating a new one. An omitted or emptylicenseConfigsmeans the subscription will have no product profile attached. list_servicesreturns a very large payload that exceeds the inline token limit. When you need to find an API code or inspect its details, search the saved file with a shell command (e.g.python3 -c "import json; ..."filtering by name/code) rather than reading the full response inline.