Understanding organizations

This page applies to Apigee and Apigee hybrid.

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. Paid organizations include those created as part of a Subscription or a Pay-as-you-go Apigee pricing model.
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.

Eval org lifespan

Eval orgs have a limited lifespan:

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

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 Apigee organization belongs to exactly one Google Cloud project, and a project can contain at most one organization. An organization contains environments, 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. Note: Non-Subscription accounts are limited to creating only a single organization—though you can still be a member of multiple existing organizations.
Environments and environment groups	An environment is an isolated software environment, within an organization, where you deploy API proxies. You can create multiple environments in an organization. An environment group is a group of environments with one or more hostnames. The hostname is part of the URL used to call API proxies deployed to any environment in the environment group.
API proxy	An API proxy is an interface between incoming requests and backend services. The proxy entity contains the instructions and policies that Apigee executes as it processes requests from clients and responses from the backend.
API product	An entity for publishing APIs. API Products get published to the developer portal for consumption by external developers. An API Product presents an interface for accessing one or more published APIs. The interface (which may be described using an OpenAPI specification) may include a combination of one or more of the API requests that are handled by one or more API proxies. The users in an organization create API products. When doing so, they can attach arbitrary metadata to each API Product. One commonly-used type of metadata can define a service plan, which can specify access limits on API calls, stipulate security requirements, allow monitoring and analytics, and provide additional features. Apigee collects data for analytics on API products.
API provider	The person or entity that creates and manages API proxies and products. Client app developers access these published APIs.
App Developer	An organization contains one or more developers who build the apps that consume the APIs (published as 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 may or may not pay for access to your APIs. You can think of developers as customers who use your APIs. 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 creating client applications that call APIs requiring credential checks (such as API keys or OAuth tokens) must first create an App registration with your organization. An App registration provides the developer with the API key, a key/secret pair, or other credentials that must be used when the client application calls 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.

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

If the API provider specifies API key verification as the authorization mechanism, the client application must pass an API key with every request to your APIs. If that key is valid, Apigee allows the request. Alternatively, if the API provider specifies OAuth token verification as the authorization mechanism, the client application must first obtain an OAuth token, and then pass that token with every request to your APIs. If that token is valid, Apigee allows the request. Other custom authorization schemes are possible.

As an API provider, you must define a way for developers to register their apps. Each app registration will have one or more keys or credentials associated to it. If you allow developers to register their own applications via a developer portal, the developer can retrieve the key or credential required to access your APIs, via a convenient, self-service experience.

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/credential to access all API products associated with the app.

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 an expiry 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 add users to an organization.

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, even though internally, 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 organization to be a user. An administrator can add you to an existing organization.

All users log in to Apigee here: Apigee UI.

Entitlements

Organization entitlements depend upon whether the paid organization uses a Subscription or Pay-as-you-go pricing model.

Subscription entitlements

Organizations: Organization entitlement is expressed in units. When you obtain an organization unit entitlement, you can use it to enable a single new organization in any region you want or to extend an existing organization into a single new region (using domain name expansion). For the purpose of entitlements, an organization in N regions consumes N organization units. For example, if you buy four new organization units, you can:

expand an existing organization into four new regions,
or expand each of 2 existing organizations into two new regions,
or create four new organizations, each available in one region.

Your total organization-unit entitlement is the aggregate of your Subscription tier plus relevant Organization Packs.

Environments: Environment entitlements are also expressed in units. They are independent of organization entitlements, and behave differently. There is a two-step process to using an environment unit entitlement: first you create an environment and then you attach that environment to an organization. An environment counts against your environment unit entitlement when the environment has been attached to an organization.

Environment unit usage is calculated as 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 consume two environment units from your entitlement.

Your total environment unit entitlement is the aggregate of the entitlement supplied in your Subscription tier plus additional entitlement obtained via Environment or Organization Packs. Buying an Organization Pack gives you one organization unit and some number of environment units. Any environment unit entitlement added via an Organization Pack is independent of any organization you choose to create or expand. Environment unit entitlements added via Organization Packs simply add to your total environment unit entitlement. To add more environment units without purchasing additional organization units, you can buy an Environment Pack.

For more details, see Subscription entitlements.

Pay-as-you-go entitlements

Organizations: The Pay-as-you-go pricing model entitles account holders to a single organization.

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.

The Pay-as-you-go pricing model includes an entitlement of 85 environments across all regions.

For more details, see Pay-as-you-go entitlements.