Understanding organizations

You're viewing Apigee X documentation.
View Apigee Edge documentation.

An organization is the top-level container in Apigee. It contains all your API proxies and related resources. While the rest of this topic goes into more depth about organizations, here are a few practical points:

  • Once created, you cannot rename an organization.
  • Your organization name is in the URL of the Apigee UI. For example:
    https://apigee.google.com/organizations/ORG_ID
  • When you make calls with the Apigee API, the organization is a required part of the path in most calls. For example, the following curl request returns a list of all API proxies in an organization using the organizations API:
    curl https://apigee.googleapis.com/v1/organizations/YOUR_ORG_ID/apis
  • While you may have created only one organization, you can belong to other organizations as a user or administrator with specific permissions. You can switch to a different organization as described in Switching between your organizations.
  • An Apigee organization is not the same as a Google Cloud organization. Where the possibility of ambiguity exists, this document specifies that the "organization" is an Apigee organization.

Video: Watch a short video to learn how organizations support a multi-tenancy architecture for API management.

Organization types

There are two types of organizations:

  • Paid: A permanent organization with full scalability. Also known as a production organization. Creating a paid organization requires a contract with Apigee.

    Apigee grants you entitlements per your contract so that you can create this kind of organization, as described in Overview and prerequisites.

  • Evaluation: A temporary, self-service organization for testing Apigee. Also known as eval orgs, these organizations are time-limited and lack the scalability and flexibility of production organizations.

    You create, or provision, your own eval org without any entitlements, as described in Creating an evaluation organization.

Eval org lifespan

Eval orgs have a limited lifespan:

  1. Day 0: Create the eval org.
  2. Day 30: Google sends you an email notification warning of the upcoming eval expiration.
  3. Day 60: Google deletes the eval org.

Comparing eval and paid organizations

Both paid and evaluation organizations have full functionality; the differences between them lay mostly in scaling and infrastructure allowances, as the following table shows:

Function Org Type Description
Paid/Production Evaluation
Lifespan Based on contract 60 days For an eval org, you will get a notification after 30 days that its lifespan is limited. After 60 days, Google deletes the eval org. You cannot extend its lifespan.
Requires VPC peering? Both require VPC peering.
Required peering network size /16 or /20 /22 For more information, see Peering ranges.
Proxy access External or private/local access External or private/local access By default, API proxies can be accessed internally only. You can, however, configure your load balancer to accept external requests for either an eval or paid account.
Supported instances Based on contract 1 The number of runtime instances.
Environments Based on contract and CIDR range 2

The number of runtime environments. Does not affect the number of environment groups.

Apigee creates two environments during provisioning, so an eval org must delete one to create a new one.

If your CIDR range is /20 then your maximum number of environments is 14. For more information, see Peering ranges.

Runtime fault tolerance Regional Regional

Runtimes in eval orgs run in a single zone only; if that zone goes down, then the eval org will be unavailable.

Runtimes for production orgs use regional clustering, which means that if a zone goes down, Apigee can re-route requests to the runtimes in other zones within the region.

For more information about regions and zones, see Regions and zones.

Analytics data Regional Regional

Analytics data is regional for both.

Customer managed encryption keys for runtime data Yes No
SLA Yes. See Apigee Service Level Agreement (SLA) No
Scalability and sizing Evaluation orgs have limited/restricted infrastructure. They are not suitable for performance/load testing.

For additional information, see Apigee Pricing.

Organization components

The following image shows the major components of the Apigee organizational model. This model defines how your APIs, API products, apps, and app developers are all related within Apigee.

Hierarchical diagram showing the organization as the root of an Apigee deployment.

This model does not show all of the features of Apigee, but it is meant to show you that the organization is the root of a deployment.

The following table describes the components of the organizational model in more detail:

Component Description
Organization

Every Google Cloud account maps to one organization. The organization contains a representation of all environments, plus API proxies, API products, API packages, apps, and users.

Account holders are not limited to a single organization. Some account holders might define or be a member of multiple organizations that support different app developer communities.

Environments and environment groups A runtime execution context for the API proxies in an organization. For more information, see About environments and environment groups.

API proxy

An API proxy defines a mapping of a publicly available HTTP endpoint to a backend service. API proxies can also be configured to include security (such as OAuth), perform message transformation (such as XML to JSON), limit traffic to backend services, and perform other valuable operations on the request, the response, and with service callouts.

The users in an organization create one or more API proxies.

Google collects data for analytics on API proxies.

API product

A bundle of API proxies combined with a service plan. That service plan can specify access limits on API proxies, provide security, allow monitoring and analytics, and provide additional features.

The users in an organization create API products.

Apigee collects data for analytics on API products.

API provider

The entity that creates and manages API proxies. Client app developers access API proxies.

App Developer

An organization contains one or more developers who build the apps that consume the APIs (assembled into API products) defined by your organization. Developers consume APIs but cannot create APIs or perform any other actions in the organization.

Developers can be internal to your company, they can be partners, or they can be external developers who pay for access to your APIs. You might think of some developers as customers.

Developers must be registered in your organization before they can register an app and receive an API key to access your APIs. As an API provider, it is up to you to determine how to add, update, or remove developers in your organization. You can manually add them through the UI, create a developer portal to register them through a website, or define your own registration mechanism by using the Apigee API.

Apigee App (or App)

Apigee developers create one or more client apps that consume your APIs.

Developers must register their apps with your organization. An app is a representation of a developer's actual app that provides the developer with an API key to pass in with every request to your APIs.

Because all apps are registered in your organization, you can use Apigee to monitor and collect analytic information on the app and on its use of your APIs.

Additional components of Apigee that are not shown are the API keys and OAuth tokens.

Depending on the authorization mechanism that you define for your APIs, the Apigee app passes an API key with every request to your APIs. If that key is valid, the request is allowed.

Apigee supports different types of authentication, such as a simple API key, two-legged OAuth, three-legged OAuth, and others.

As an API provider, you must define a way for developers to register their apps. It is by registering their app that you return to the developer the key required to access your APIs.

At the time of app registration, developers can choose to access a single API product or multiple API products. A developer's app uses the same key to access all API products associated with the app (the registered representation of the developer's app in Apigee).

At any time, you can revoke the key so that the developer's app no longer has access to your APIs (even though the registered representation of the developer's app still exists in your organization). Or, you can define a time limit on a key so that the developer must refresh the key after a specific time.

Apigee users

Apigee users make up the organization's API team, which can include people such as administrators, API proxy and API product creators, or users monitoring analytics and other statistics. End-users are people who use the apps that Apigee developers build. In most cases, this documentation uses the term "user" to refer to an Apigee user.

Administrators can create more users.

Different users can have different roles and access privileges. For example, define some users as Organization Administrators and Operations Administrators with privileges to modify the organization and its components. Define other users with permissions to create API proxies and API products, but without the privileges to modify other users.

Users can be members of multiple organizations. For example, your company might define multiple organizations on Apigee to support different developer communities. Internally though, the same people build all of the API proxies and API products and are therefore members of all of your organizations.

You don't have to create an Apigee account—that is, create an Apigee organization—to be a user. An administrator can add you to an existing organization.

All users log in to Apigee here: Apigee UI.

Entitlements

Organizations: When you entitle a new organization, you can use it as a new organization in any region you want or to extend an existing origanization into a new region (using domain name expansion). For example, if you buy four new organizations, you can expand an existing organization into four new regions. For the purpose of entitlements, an organization in two regions is the same as two organizations.

Your total organization entitlement is the aggregate of your subscription tier plus relevant Org Packs.

Environments: Environment entitlements are independent of organization entitlements. They also behave differently than organization entitlements in that there is a two step process to using them: first you create an environment and then you attach that environment to an organization. Environments do not count against your entitlement limits until they have been attached to an organization.

To put it another way, the number of environments that count toward your entitlement is the number of environments that have been attached to an organization.

Your total environment entitlement is the aggregate of your subscription tier plus relevant packs. Any environments added from an Org Pack are independent and not tied to the new organization. They add to your total environment entitlement.

Environment usage is the number of environments used across all organizations and each region. In other words, an environment that is provisioned in two regions for one organization will count as two environments against your entitlement cap.

To add more environments without purchasing additional organizations, you can buy an Environment Pack.