DEV Community

Mahmoud Sayed
Mahmoud Sayed

Posted on

Apigee API Products, Developer, Apps and API Keys

#apigee #apigateway #api #googlecloud

The Big Picture: The Apigee Security Model

Apigee uses a API Key as the primary credential for API access. This key is not created in isolation; it's the result of a relationship between a Developer, their App, and the API Products that app is authorized to consume.

Here’s the flow of how they work together:

  1. You (the API provider) publish an API Product.
  2. A Developer registers in your developer portal.
  3. The Developer creates an App and selects which API Products it needs access to.
  4. Apigee generates a unique API Key for that App.
  5. The Developer includes this key in the requests their App makes.
  6. Apigee checks if the key is valid and if it provides access to the requested API Product.

1. API Product

An API Product is a bundle of API resources (proxies) that you, as the API provider, offer to developers. It's the main commercial and legal unit of consumption. It defines:

  • Which Proxies/Endpoints: Which API proxies (and their specific paths) are included.
  • Quotas: How many requests can be made per minute, hour, day, etc.
  • Access Policies: Who can access it (e.g., internal vs. external developers).

Think of it like a **"cable TV package". You don't buy individual channels; you buy a package (e.g., "Sports Lite" or "Movie Lover Bundle").**

Example:
You work at CompanyX and have built several APIs. You create two products:

  • CompanyX-Free-Tier
    • Proxies Included: weather-api, news-api
    • Quota: 100 calls per day, 5 calls per minute
    • Environments: test (for trying it out)
  • CompanyX-Premium-Weather
    • Proxies Included: weather-api (includes all endpoints, even the premium ones like historical data)
    • Quota: 10,000 calls per day, 100 calls per minute
    • Environments: test, prod

2. Developer

A Developer represents a user or a company that consumes your APIs. They are typically registered through your developer portal.

  • They are the entity that owns Apps.
  • They have a profile with contact information (email, name).

Think of them as the **"account holder" for the cable TV subscription.**

Example:

  • Developer Name: Jane Smith
  • Email: jane.smith@example.com
  • Company: Cool Mobile Apps Inc.

3. App

An App is a specific project or application created by a Developer that needs to call your APIs. A single Developer can have multiple Apps (e.g., an iOS app and an Android app).

  • The App is the entity that is granted access to API Products.
  • When an App is approved for an API Product, Apigee generates credentials (API Keys) for it.

Think of it as the **"set-top box" in a specific room. The account holder (Developer) can have multiple set-top boxes (Apps), each with its own remote (API Key), all under the same subscription plan (API Products).**

Example:
Developer Jane Smith creates two apps:

  • App Name: Weather-Widget-iOS
    • Purpose: Her company's iOS weather application.
  • App Name: Weather-Widget-Android
    • Purpose: Her company's Android weather application.

4. API Key

The API Key is a unique string (like a password) that is generated for a specific App. It is the secret token that must be presented in every API request to Apigee (usually in the x-apikey header or as a query parameter).

  • Apigee validates this key to:
    1. Authenticate: Is this a key I issued? Is it active?
    2. Authorize: Does the App that owns this key have permission to access the specific API Product that contains the requested API proxy?

Think of it as the **"unique signal" or "authorization card" for that specific set-top box (App). Without it, you can't get the channels (APIs) you subscribed to.**

Example:

  • For the App Weather-Widget-iOS, Apigee generates:
    • API Key: Rz4uP91KQ2m5cLb3Fv6Hs8dJqA0xWnEy

  • This key is configured in the app's code. Every API call includes it:

    curl -H "x-apikey: Rz4uP91KQ2m5cLb3Fv6Hs8dJqA0xWnEy" \
  "https://companyx.apigee.net/v1/weather/forecast?city=London"

How It All Fits Together: A Practical Example

Let's walk through the entire lifecycle.

Step 1: API Provider (You) creates API Products.

  • You create CompanyX-Free-Tier and CompanyX-Premium-Weather.

Step 2: Developer (Jane) signs up.

  • Jane signs up on dev.companyx.com and her account is created.

Step 3: Developer (Jane) creates an App.

  • Jane logs in, goes to her dashboard, and clicks "New App".
  • She names it Weather-Widget-iOS.
  • She checks the box to request access to the CompanyX-Free-Tier product.

Step 4: API Provider (You) approves the request.

  • (This can also be automatic). You approve her app's access to the free tier.

Step 5: Apigee generates Credentials.

  • In Jane's developer portal dashboard, she can now see her App Weather-Widget-iOS.
  • On its details page, a new API Key (e.g., Rz4uP91KQ2m5cLb3Fv6Hs8dJqA0xWnEy) is displayed. This key is automatically approved for the CompanyX-Free-Tier product.

Step 6: The App makes a call.

  • Jane's iOS developer codes the app to include the API key in all requests.
  • The app calls: https://companyx.apigee.net/v1/weather/forecast?city=London

Step 7: Apigee validates the call.
When the request hits Apigee, it performs these checks almost instantly:

  1. "Is the key Rz4uP91KQ2m5cLb3Fv6Hs8dJqA0xWnEy valid and active?" -> Yes, it belongs to the App Weather-Widget-iOS.
  2. "What API Products is this App approved for?" -> CompanyX-Free-Tier.
  3. "Does the CompanyX-Free-Tier product include the proxy and path being called (/v1/weather/forecast)?" -> Yes, it includes the weather-api proxy.
  4. "Has the App exceeded its quota (100/day)?" -> No, it's only made 50 calls today.
  5. ✅ Validation passed! The request is forwarded to the backend weather service.

If Jane had tried to call a premium endpoint like /v1/weather/historical, step 3 would have failed because her CompanyX-Free-Tier product does not include that endpoint. Apigee would block the request and return a 403 Forbidden error.

This model provides a powerful, flexible, and auditable way to manage and monetize API access.

Here are flowcharts that visualize the relationships between API Products, Developers, Apps, and API Keys in Apigee, from both the provider's and consumer's perspectives.

Flowchart 1: Provider's Administrative View (How Things Are Built)

This chart shows how you, the API provider, assemble and offer an API Product.

flowchart TD
    A[API Provider] --> B[Create API Proxies]

    subgraph Proxies [Backend Services]
        B1[weather-api]
        B2[news-api]
        B3[payment-api]
    end

    B --> Proxies

    Proxies --> C[Bundle into API Products]

    subgraph Products [API Products - The 'Packages']
        P1[Free-Tier]<br>Includes: B1, B2<br>Quota: 100/day
        P2[Premium-Weather]<br>Includes: B1 all endpoints<br>Quota: 10,000/day
    end

    C --> Products
    Products --> D[Publish to Developer Portal]
    D --> E[Developers Discover & Subscribe]
Enter fullscreen mode Exit fullscreen mode

Flowchart 2: Consumer's Journey (How Access is Granted)

This chart shows the process a developer follows to get and use an API key.

flowchart TD
    A[Developer] --> B[Signs up on Developer Portal]
    B --> C[Creates an 'App' e.g. Weather-Widget-iOS]
    C --> D[Requests access to an API Product e.g. Free-Tier]
    D --> E{Provider Approval<br>Auto or Manual}
    E -- Approved --> F
    E -- Rejected --> G[Access Denied]
    F[Apigee Generates Unique API Key for that App] --> H[Developer embeds Key in App Code]
    H --> I[App makes API call with Key]
    I --> J{Apigee Verification}

    subgraph J [Verification Steps]
        J1[Key Valid?]
        J2[Product Approved?]
        J3[URL Path Included?]
        J4[Quota Available?]
    end

    J -- All Checks Pass --> K[Request forwarded to Backend]
    J -- Any Check Fails --> L[Error e.g. 403 Forbidden]
Enter fullscreen mode Exit fullscreen mode

Flowchart 3: Runtime Request Flow (What Happens on Every API Call)

This chart details the specific verification steps Apigee performs for every incoming request.

flowchart LR
    A[Incoming API Request<br>with API Key] --> B{Verify API Key}
    B -- Invalid/Revoked --> C[Block Request: 401 Unauthorized]
    B -- Valid --> D[Look Up App & Developer Details]
    D --> E{Check API Product Access}
    E -- Product not approved<br>for this URL --> F[Block Request: 403 Forbidden]
    E -- Product approved --> G{Check Quota & Rate Limits}
    G -- Quota Exceeded --> H[Block Request: 429 Too Many Requests]
    G -- Quota Available --> I[Allow Request to Backend]
    I --> J[Log Analytics Data<br>e.g. for App, Developer, Product]
Enter fullscreen mode Exit fullscreen mode

Key Relationships Visualized

The core relationship between the entities can be summarized in this hierarchy:

API Product (The "Package")
    ^
    | contains
    |
API Proxies (The "Channels")
    ^
    | is accessed via
    |
App (The "Set-Top Box")
    ^
    | owns
    |
Developer (The "Account Holder")
    ^
    | uses
    |
API Key (The "Signal"/Password)
Enter fullscreen mode Exit fullscreen mode

This shows that an API Product bundles Proxies. An App (owned by a Developer) is approved for a product. The API Key is the credential for that specific App, granting it the rights of the product it's approved for.

Top comments (0)