--- name: request-api-access description: | Request access to a published API in an API Experience Hub portal by creating a contract between one of your applications and a specific API instance/tier. Use when a portal consumer needs to discover available tiers and grant types, create a contract, review existing contracts, or change an SLA tier on an active contract. --- > **Agent context:** For execution instructions, authentication, input types, and x-origin resolution, read [https://dev-portal.mulesoft.com/AGENTS.md](https://dev-portal.mulesoft.com/AGENTS.md). # Request API Access ## Overview In AEH, "access" to an API is granted via a **contract**: a binding between one of your applications and a specific API instance (e.g., sandbox/production) under a chosen SLA tier. This workflow covers the full consumer-side request flow: discovering the tiers and grant types offered, creating a contract, listing your contracts, and adjusting the SLA tier later. **What you'll build:** Active contracts between your applications and the APIs you need, on the right SLA tiers. ## Prerequisites Before starting, ensure: 1. **Authentication ready** - Valid portal-consumer Bearer token - Membership in the portal 2. **Portal and application context** - `targetOrganizationId`, `portalId` - An existing `applicationId` (see `manage-portal-applications` to create one) - Target asset coordinates: `groupId`, `assetId`, `minorVersion`, `instanceId` (see `discover-portal-apis` Step 3) ## Step 1: List Available SLA Tiers for an Instance Tiers define throughput/quota limits and governance rules for an API instance. Some instances require a tier selection; others default to an implicit tier. **What you'll need:** - `targetOrganizationId`, `portalId` - `groupId`, `assetId`, `minorVersion`, `instanceId` ```yaml api: urn:api:api-experience-hub-consumer operationId: getTiers inputs: targetOrganizationId: userProvided: true description: Anypoint organization ID hosting the portal portalId: userProvided: true description: Portal ID the user belongs to groupId: userProvided: true description: Exchange groupId of the target asset assetId: userProvided: true description: Exchange assetId of the target asset minorVersion: userProvided: true description: Minor version the consumer wants access to instanceId: userProvided: true description: API instance ID (environment) to contract against outputs: - name: tiers path: $.tiers[*] labels: $.tiers[*].name description: SLA tiers offered on this instance - name: tierId path: $.tiers[*].id description: Tier ID passed to the create-contract call ``` ## Step 2: List Grant Types Offered by the API Instance Grant types (`client_credentials`, `authorization_code`, etc.) describe how your application will obtain tokens. Some APIs require that at least one grant type matches between API and application. **What you'll need:** - `targetOrganizationId`, `portalId`, `instanceId` ```yaml api: urn:api:api-experience-hub-consumer operationId: getGrantTypesByInstanceId inputs: targetOrganizationId: from: variable: targetOrganizationId description: Anypoint organization ID hosting the portal portalId: from: variable: portalId description: Portal ID instanceId: from: variable: instanceId description: API instance ID outputs: - name: instanceGrantTypes path: $.grantTypes[*] description: Grant types the instance supports ``` ## Step 3: List Grant Types Supported by Your Application Cross-check your application's supported grant types against the instance's. **What you'll need:** - `targetOrganizationId`, `portalId`, `applicationId` ```yaml api: urn:api:api-experience-hub-consumer operationId: getGrantTypesByApplicationId inputs: targetOrganizationId: from: variable: targetOrganizationId description: Anypoint organization ID hosting the portal portalId: from: variable: portalId description: Portal ID applicationId: userProvided: true description: ID of the application that will hold the contract outputs: - name: applicationGrantTypes path: $.grantTypes[*] description: Grant types the application can use ``` **What happens next:** Confirm at least one grant type overlaps between Step 2 and Step 3 before creating the contract. ## Step 4: Create a Contract Bind the application to the API instance under the chosen tier. **What you'll need:** - `targetOrganizationId`, `portalId` - `groupId`, `assetId`, `minorVersion` - `applicationId`, optional `tierId` ```yaml api: urn:api:api-experience-hub-consumer operationId: createContract inputs: targetOrganizationId: from: variable: targetOrganizationId description: Anypoint organization ID hosting the portal portalId: from: variable: portalId description: Portal ID groupId: from: variable: groupId description: Exchange groupId of the target asset assetId: from: variable: assetId description: Exchange assetId of the target asset minorVersion: from: variable: minorVersion description: Minor version for the contract contractRequest: userProvided: true description: Contract payload (application, tier, optional custom fields) example: applicationId: a1b2c3d4-0000-0000-0000-000000000000 tierId: 12345 acceptedTerms: true outputs: - name: contractId path: $.id description: The newly created contract ID (may be PENDING until approved) - name: contractStatus path: $.status description: Current status — typically APPROVED or PENDING ``` **What happens next:** If the API requires admin approval, the contract is `PENDING`. Otherwise it is immediately `APPROVED` and the application can call the API. ## Step 5: List Contracts for an Application Audit which APIs a specific application currently has (or has requested) access to. **What you'll need:** - `targetOrganizationId`, `portalId`, `applicationId` ```yaml api: urn:api:api-experience-hub-consumer operationId: getContractsByApplicationId inputs: targetOrganizationId: from: variable: targetOrganizationId description: Anypoint organization ID hosting the portal portalId: from: variable: portalId description: Portal ID applicationId: from: variable: applicationId description: Application to audit outputs: - name: applicationContracts path: $.contracts[*] labels: $.contracts[*].assetName description: Contracts held by this application - name: contractIds path: $.contracts[*].id description: Contract IDs for deeper inspection ``` ## Step 6: Get Contract Details Retrieve the full state of one contract — useful to verify status, tier, and SLA usage. **What you'll need:** - `targetOrganizationId`, `portalId`, `applicationId`, `contractId` ```yaml api: urn:api:api-experience-hub-consumer operationId: getContract inputs: targetOrganizationId: from: variable: targetOrganizationId description: Anypoint organization ID hosting the portal portalId: from: variable: portalId description: Portal ID applicationId: from: variable: applicationId description: Application holding the contract contractId: from: variable: contractIds description: Specific contract ID outputs: - name: contractDetails path: $ description: Full contract details (status, tier, associated asset/instance) ``` ## Step 7: Change the SLA Tier on an Active Contract Upgrade or downgrade the SLA tier — e.g., from Bronze to Gold as consumption grows. **What you'll need:** - `targetOrganizationId`, `portalId`, `applicationId`, `contractId` - New `tierId` chosen from Step 1 ```yaml api: urn:api:api-experience-hub-consumer operationId: assignSlaTierToContract inputs: targetOrganizationId: from: variable: targetOrganizationId description: Anypoint organization ID hosting the portal portalId: from: variable: portalId description: Portal ID applicationId: from: variable: applicationId description: Application holding the contract contractId: from: variable: contractIds description: Contract whose tier is changing tierId: from: variable: tierId description: New SLA tier ID outputs: - name: updatedContractId path: $.id description: Contract ID confirmed with the new tier applied ``` **What happens next:** Depending on portal policy, the new tier may apply immediately or wait for admin approval. ## Completion Checklist - [ ] Available tiers reviewed - [ ] Grant types cross-checked between application and instance - [ ] Contract created - [ ] Contract status verified (APPROVED vs PENDING) - [ ] Existing contracts for the application audited - [ ] SLA tier adjusted when consumption changes ## What You've Built ✅ **Active Contract(s)** — Your applications are bound to the APIs you need on the correct SLA tiers, with grant types that match. ## Next Steps 1. **Call the API** — Use the application's `clientId` / `clientSecret` (from `manage-portal-applications`) to obtain tokens per the chosen grant type. 2. **Monitor usage** — Track quota/throughput against the chosen tier; upgrade via Step 7 when you hit limits. ## Related Jobs - **discover-portal-apis** — Find the asset, instance and tiers to request - **manage-portal-applications** — Manage the applications that hold contracts