# Request API Access

> 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.

- Skill: `mulesoft/request-api-access` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mulesoft/request-api-access`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mulesoft/request-api-access/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: mulesoft (https://skillmd.com/u/mulesoft)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mulesoft/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`

```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