Step 2: Create an organization

In this step, you create anApigee organization.

Note:An Apigee organization is the top-level container in Apigee. The Apigee organization contains all your API proxies and related resources. Apigee organizations are not the same as Google Cloud organizations.

For an overview of Apigee organizations, see Organization structure.
For information about Google Cloud organizations, seeOrganizations.

About organization creation

When provisioning an organization, note the following:

You cannot provision Apigee hybrid in an existing Apigee organization. You must create a new organization and the organization name must match the Google Cloud project ID.
An organization is bound to a single Google Cloud project.

To create a new organization and provision it:

Note:If you have an Apigee evaluation account, theorganization you create will expire after 60 days. At that time, the organization willbe deleted.

If this occurs, you may encounter the following error:"Project <my-project> doesn't have an Apigee organization provisioned." To resolve this error, follow the steps to create a new organization and provision it.

On the command line, get yourgcloud authentication credentials using the following command:

Linux / MacOS

export TOKEN=$(gcloud auth print-access-token)

To check that your token was populated, useecho, as the following example shows:

echo $TOKEN

This should display your token as an encoded string.

Windows

for /f "tokens=*" %a in ('gcloud auth print-access-token') do set TOKEN=%a

To check that your token was populated, useecho, as the following example shows:

echo %TOKEN%

This should display your token as an encoded string.

In Step 1, you created thePROJECT_ID environment variable. Add the following environment variables. Select the tab that corresponds to the type of organization you need:No data residency or withData residency:
No data residency
Linux / MacOS
export ORG_NAME=$PROJECT_IDexport ANALYTICS_REGION="ANALYTICS_REGION"export RUNTIMETYPE=HYBRID
Windows
set ORG_NAME=$PROJECT_IDset ANALYTICS_REGION="ANALYTICS_REGION"set RUNTIMETYPE=HYBRID
Tip: Use theecho %variable-name% command to verify that the environment variables are properly set.
Where:
- ORG_NAME(Required): This value must match thePROJECT_ID.
- ANALYTICS_REGION(Required): The primary region for analytics data storage. For a list of available Apigee API Analytics regions, see Apigee locations.
- RUNTIMETYPE(Required): Must be set toHYBRID.
Data residency
Linux / MacOS
export ORG_NAME=$PROJECT_IDexport RUNTIMETYPE=HYBRIDexport CONTROL_PLANE_LOCATION="YOUR_CONTROL_PLANE_LOCATION"export CONSUMER_DATA_REGION="YOUR_CONSUMER_DATA_REGION"export BILLING_TYPE="SUBSCRIPTION"
Windows
set ORG_NAME=$PROJECT_IDset RUNTIMETYPE=HYBRIDset CONTROL_PLANE_LOCATION="YOUR_CONTROL_PLANE_LOCATION"set CONSUMER_DATA_REGION="YOUR_CONSUMER_DATA_REGION"set BILLING_TYPE="SUBSCRIPTION"
Tip: Use theecho %variable-name% command to verify that the environment variables are properly set.
Where:
- ORG_NAME: This value must match thePROJECT_ID.
- RUNTIMETYPE: Must be set toHYBRID.
- CONTROL_PLANE_LOCATION: The location where customer core content like proxy bundles is stored. For a list see Available Apigee API control plane regions.
- CONSUMER_DATA_REGION: A sub-region of the control plane region. You must specify both theCONTROL_PLANE_LOCATION and theCONSUMER_DATA_REGION. For a list of available consumer data regions, see Apigee locations.
- BILLING_TYPE: Must be set to"SUBSCRIPTION". This is the billing type for your Apigee hybrid organization. SeeSubscription entitlements for more information.
For example:
```
export ORG_NAME=$PROJECT_IDexport RUNTIMETYPE=HYBRIDexport CONSUMER_DATA_REGION="us-west1"export CONTROL_PLANE_LOCATION="us"export BILLING_TYPE="SUBSCRIPTION"
```

Call the following Apigee API to create the organization:

No data residency

curl -H "Authorization: Bearer$TOKEN" -X POST -H "content-type:application/json" \  -d '{    "name":"'"$ORG_NAME"'",    "runtimeType":"'"$RUNTIMETYPE"'",    "analyticsRegion":"'"$ANALYTICS_REGION"'"  }' \  "https://apigee.googleapis.com/v1/organizations?parent=projects/$PROJECT_ID"

Data residency

curl -H "Authorization: Bearer$TOKEN" -X POST -H "content-type:application/json" \  -d '{    "name":"'"$ORG_NAME"'",    "billingType":"'"$BILLING_TYPE"'",    "runtimeType":"'"$RUNTIMETYPE"'",    "apiConsumerDataLocation":"'"$CONSUMER_DATA_REGION"'"  }' \  "https://$CONTROL_PLANE_LOCATION-apigee.googleapis.com/v1/organizations?parent=projects/$PROJECT_ID"

Tip:The quotation mark structure ("'") in the previous code sample is needed to pass the values of the environment variables within the JSON body.

On a successful creation request, the organizations API responds with a message similar to the following:

{"name":"organizations/org_name/operations/LONG_RUNNING_OPERATION_ID","metadata":{"@type":"type.googleapis.com/google.cloud.apigee.v1.OperationMetadata","operationType":"INSERT","targetResourceName":"organizations/org_name","state":"IN_PROGRESS"}}

Where:

LONG_RUNNING_OPERATION_ID is the UUID of an asynchronous, long-running operation. You can use this ID to check the status of your organization creation request (described in step 5).
org_name is the ID of your new organization that is currently being created.

As thestate property in the response indicates, Apigee has started to create the new organization, so its state isIN_PROGRESS. This process can take several minutes.

If you get an error, see Troubleshooting organization creation.

Save the long-running operation ID to an environment variable. It will be useful for future management tasks.

Syntax

export LONG_RUNNING_OPERATION_ID=LONG_RUNNING_OPERATION_ID

Example

export LONG_RUNNING_OPERATION_ID=6abc8a72-46de-f9da-bcfe-70d9ab347e4f

You can check the status of the long-running operation whose ID was returned by the creation request. To do this, use the operations API. For example:

No data residency

curl -H "Authorization: Bearer$TOKEN" \  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/operations/$LONG_RUNNING_OPERATION_ID"

The following examples show possible responses to this request:

IN_PROGRESS

If Apigee is still creating the organization, Apigee responds with a status ofIN_PROGRESS. For example:

{"name":"organizations/ORG_NAME/operations/LONG_RUNNING_OPERATION_ID","metadata":{"@type":"type.googleapis.com/google.cloud.apigee.v1.OperationMetadata","operationType":"INSERT","targetResourceName":"organizations/ORG_NAME","state":"IN_PROGRESS"}}

You should wait a little longer before attempting to verify that the creation process is complete.

FINISHED

When the organization has been provisioned, the state of the long-running operation isFINISHED. For example:

{"name":"organizations/ORG_NAME/operations/LONG_RUNNING_OPERATION_ID","metadata":{"@type":"type.googleapis.com/google.cloud.apigee.v1.OperationMetadata","operationType":"INSERT","targetResourceName":"organizations/ORG_NAME","state":"FINISHED"},"done":true,"response":{"@type":"type.googleapis.com/google.cloud.apigee.v1.Organization","name":"ORG_NAME","description":"","createdAt":"1626237148461","lastModifiedAt":"1626237149384","properties":{"property":[{"name":"features.hybrid.enabled","value":"true"},{"name":"features.mart.connect.enabled","value":"true"}]},"analyticsRegion":"ANALYTICS_REGION","runtimeType":"HYBRID","subscriptionType":"TRIAL","state":"ACTIVE","billingType":"EVALUATION","expiresAt":"1631421073171","addonsConfig":{"advancedApiOpsConfig":{},"integrationConfig":{},"monetizationConfig":{}}}}

Data residency

curl -H "Authorization: Bearer$TOKEN" \  "https://$CONTROL_PLANE_LOCATION-apigee.googleapis.com/v1/organizations/$ORG_NAME/operations/$LONG_RUNNING_OPERATION_ID"

The following examples show possible responses to this request:

IN_PROGRESS

If Apigee is still creating the organization, Apigee responds with a status ofIN_PROGRESS. For example:

{"name":"organizations/ORG_NAME/operations/LONG_RUNNING_OPERATION_ID","metadata":{"@type":"type.googleapis.com/google.cloud.apigee.v1.OperationMetadata","operationType":"INSERT","targetResourceName":"organizations/ORG_NAME","state":"IN_PROGRESS","progress":{"percentDone":30}}}

You should wait a little longer before attempting to verify that the creation process is complete.

FINISHED

When the organization has been provisioned, the state of the long-running operation isFINISHED. For example:

{"name":"organizations/ORG_NAME/operations/LONG_RUNNING_OPERATION_ID","metadata":{"@type":"type.googleapis.com/google.cloud.apigee.v1.OperationMetadata","operationType":"INSERT","targetResourceName":"organizations/ORG_NAME","state":"FINISHED"},"done":true,"response":{"@type":"type.googleapis.com/google.cloud.apigee.v1.Organization","name":"ORG_NAME","description":"","createdAt":"1626237148461","lastModifiedAt":"1626237149384","properties":{"property":[{"name":"features.hybrid.enabled","value":"true"},{"name":"features.mart.connect.enabled","value":"true"}]},"analyticsRegion":"ANALYTICS_REGION","runtimeType":"HYBRID","subscriptionType":"TRIAL","state":"ACTIVE","billingType":"SUBSCRIPTION","apiConsumerDataLocation":"CONSUMER_DATA_REGION","expiresAt":"1631421073171","addonsConfig":{"advancedApiOpsConfig":{},"integrationConfig":{},"monetizationConfig":{}}}}

You can use the Apigee organizations API to retrieve information about an organization after it is created.

For example:

No data residency

curl -H "Authorization: Bearer$TOKEN" \  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME"

The response to your request contains details about the specified organization in JSON format.

{  "name": "apigee-example",  "createdAt": "1626237148461",  "lastModifiedAt": "1626237149384",  "properties": {    "property": [      {        "name": "features.hybrid.enabled",        "value": "true"      },      {        "name": "features.mart.connect.enabled",        "value": "true"      }    ]  },  "analyticsRegion": "us-west1",  "runtimeType": "HYBRID",  "subscriptionType": "PAID",  "projectId": "my-project",  "state": "ACTIVE",  "billingType": "SUBSCRIPTION",  "expiresAt": "1631421073171",  "addonsConfig": {    "advancedApiOpsConfig": {},    "integrationConfig": {},    "monetizationConfig": {}  }}

Data residency

curl -H "Authorization: Bearer$TOKEN" \  "https://$CONTROL_PLANE_LOCATION-apigee.googleapis.com/v1/organizations/$ORG_NAME"

The response to your request contains details about the specified organization in JSON format.

{  "name": "apigee-example",  "createdAt": "1626237148461",  "lastModifiedAt": "1626237149384",  "properties": {    "property": [      {        "name": "features.hybrid.enabled",        "value": "true"      },      {        "name": "features.mart.connect.enabled",        "value": "true"      }    ]  },  "analyticsRegion": "us-west1",  "runtimeType": "HYBRID",  "subscriptionType": "PAID",  "projectId": "my-project",  "state": "ACTIVE",  "billingType": "SUBSCRIPTION",  "expiresAt": "1631421073171",  "addonsConfig": {    "advancedApiOpsConfig": {},    "integrationConfig": {},    "monetizationConfig": {}  }}

Troubleshooting organization creation

When you create an organization with theCreate organizations API, you might get an error response. Responses look like the following:

{  "error": {    "code":HTTP_error_code,    "message": "short_error_message",    "status": "high_level_error_type",    "details": [      {        "@type": "specific_error_type",        "detail": "expanded_error_description"      }    ]  }}

The following table lists errors you might receive and potential resolutions when you try to create a new organization:

HTTP Error Code	HTTP Error	Description
`400`	`Invalid JSON payload received`	Either the structure of the data in your request contains a syntax error or the path to the endpoint is incorrect.
`400`	`Invalid organization ID`	The organization ID that you request cannot contain uppercase letters or any special characters other than hyphens. It must contain only lowercase letters, numbers, and/or hyphens. It can be up to a maximum of 32 characters long.
`400`	`Unsupported analytics region`	You either did not specify the value of the`analyticsRegion` in your request body, or the value you specified is not one of the valid options.
`400`	`Does not have an Apigee entitlement`	Your Google Cloud project has not yet been hybrid enabled. This could indicate an issue with your billing or some other error related to your Google Cloud account. For more information, contactApigee Sales.
`400`	`'global' violates constraint in constraints/gcp.resourceLocations on the resourceprojects/PROJECT_ID, Control Plane Region`	You tried to create an org that may not be entitled with PAID subscription. Apigee Hybrid orgs of type EVAL do not support Data Residency.
`400`	`runtimeType HYBRID is not supported for PAYG_V2, use CLOUD instead:invalid argument`	You tried to create an organization on a project with a "Pay As You Go" (PAYG) entitlement. Reach out to your Google Cloud account representative for questions about organization entitlement.
`401`	`Request had invalid authentication credentials`	Your`gcloud` authentication token is either bad or outdated, or you did not include one in the request. Generate a new token and resend the address.
`403`	`Permission denied on resource projectPROJECT_ID`	You might have sent a request that contained an incorrect project ID or path.
`403`	`Unable to retrieve project information`	The organization has not yet been created or provisioned. You can issue a request to theOperations API to check the status of the long-running operation, as described in step 5.
`403`	`Permission denied on resource project organizations/PROJECT_ID/deployedIngressConfig`	You tried to create an organization but it does not have the correct entitlements. Reach out to your Google Cloud account representative for questions about organization entitlement.
`409`	`Organization already exists`	You tried to create more than one organization for the Google Cloud project. You can only create one organization per project.
`409`	`OrgPROPOSED_ORG_NAME already exists`	You tried to create an organization that has the same ID as one that already exists. Organization IDs must be unique across all hybrid customers. Resubmit with a new proposed organization ID; for example, append a numeric value to the end of the previous ID that you tried.

Next step

Go to Step 3:Create an environment group.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.

Movatterモバイル変換

Step 2: Create an organization Stay organized with collections Save and categorize content based on your preferences.

About organization creation

Linux / MacOS

Windows

No data residency

Linux / MacOS

Windows

Data residency

Linux / MacOS

Windows

No data residency

Data residency

Syntax

Example

No data residency

IN_PROGRESS

FINISHED

Data residency

IN_PROGRESS

FINISHED

No data residency

Data residency

Troubleshooting organization creation

Next step

Step 2: Create an organization