Request API Access

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

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

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

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

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

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

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

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