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 the state property in the response indicates, Apigee has started to create
the new organization, so
its state is IN_PROGRESS. This process can take several minutes.
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 (that you created in Step 2: Create a 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, contact Apigee Sales.
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 project project_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
the Operations API to check the status of the long-running operation, as described
in step 5.
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
Org proposed_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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-26 UTC."],[[["\u003cp\u003eApigee hybrid organizations must be newly created, cannot be provisioned in an existing one, and the organization name must match the Google Cloud project ID.\u003c/p\u003e\n"],["\u003cp\u003eOrganization creation involves getting \u003ccode\u003egcloud\u003c/code\u003e authentication credentials, setting environment variables for \u003ccode\u003eORG_NAME\u003c/code\u003e, \u003ccode\u003eANALYTICS_REGION\u003c/code\u003e, and \u003ccode\u003eRUNTIMETYPE\u003c/code\u003e, and then making a POST request to the Apigee API with these values.\u003c/p\u003e\n"],["\u003cp\u003eThe creation process is asynchronous and the API will return a long-running operation ID that can be used to check the status, which may be \u003ccode\u003eIN_PROGRESS\u003c/code\u003e or \u003ccode\u003eFINISHED\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eVarious HTTP errors can occur during organization creation, including invalid JSON, unsupported regions, authentication issues, and existing organization conflicts, each with specific troubleshooting steps.\u003c/p\u003e\n"],["\u003cp\u003eApigee evaluation accounts will expire after 60 days, and the associated organization will be deleted.\u003c/p\u003e\n"]]],[],null,["# Step 2: Create an organization\n\n| You are currently viewing version 1.9 of the Apigee hybrid documentation. **This version is end of life.** You should upgrade to a newer version. For more information, see [Supported versions](/apigee/docs/hybrid/supported-platforms#supported-versions).\n\nIn this step, you create an\n[Apigee organization](/apigee/docs/api-platform/get-started/basic-concepts).\n\n### About organization creation\n\n| When provisioning an organization, note the following:\n|\n| - 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.\n| - An organization is bound to a single Google Cloud project.\n\n**To create a new organization and provision it:**\n| **Note:** If you have an Apigee evaluation account, the organization you create will expire after 60 days. At that time, the organization will be deleted.\n|\n| If this occurs, you may encounter the following error: `\"Project \u003cproject\u003e doesn't have an Apigee organization provisioned.\"`\n| To resolve this error, follow the steps to create a new organization and provision it.\n\n1. On the command line, get your `gcloud` authentication\n credentials using the following command:\n\n ### Linux / MacOS\n\n ```\n export TOKEN=$(gcloud auth print-access-token)\n ```\n\n To check that your token was populated, use `echo`, as the\n following example shows: \n\n ```\n echo $TOKEN\n ```\n\n This should display your token as an encoded string.\n\n ### Windows\n\n ```\n for /f \"tokens=*\" %a in ('gcloud auth print-access-token') do set TOKEN=%a\n ```\n\n To check that your token was populated, use `echo`, as the\n following example shows: \n\n ```\n echo %TOKEN%\n ```\n\n This should display your token as an encoded string.\n2.\n In [Step 1](/apigee/docs/hybrid/v1.9/precog-enableapi), you created the\n `PROJECT_ID` environment variable. Add these environment variables:\n\n ### Linux / MacOS\n\n export ORG_NAME=$PROJECT_ID\n export ANALYTICS_REGION=\"\u003cvar translate=\"no\"\u003eANALYTICS_REGION\u003c/var\u003e\"\n export RUNTIMETYPE=HYBRID\n\n ### Windows\n\n set ORG_NAME=$PROJECT_ID\n set ANALYTICS_REGION=\"\u003cvar translate=\"no\"\u003eANALYTICS_REGION\u003c/var\u003e\"\n set RUNTIMETYPE=HYBRID\n\n | **Tip:** Use the `echo %`\u003cvar translate=\"no\"\u003evariable-name\u003c/var\u003e`%` command to verify that the environment variables are properly set.\n\n\n Where:\n - **`ORG_NAME`** **(Required)** : This value must match the `PROJECT_ID`.\n - **`ANALYTICS_REGION`** **(Required)** : The primary region for analytics data storage. For a list of available Apigee API Analytics regions, see [Apigee locations](/apigee/docs/locations).\n - **`RUNTIMETYPE`** **(Required)** : Must be set to `HYBRID`.\n3. Call the following Apigee API to create the organization: \n\n ```\n curl -H \"Authorization: Bearer $TOKEN\" -X POST -H \"content-type:application/json\" \\\n -d '{\n \"name\":\"'\"$ORG_NAME\"'\",\n \"runtimeType\":\"'\"$RUNTIMETYPE\"'\",\n \"analyticsRegion\":\"'\"$ANALYTICS_REGION\"'\"\n }' \\\n \"https://apigee.googleapis.com/v1/organizations?parent=projects/$PROJECT_ID\"\n ```\n | **Tip:** The quotation mark structure (`\"'\"`) in the previous code sample is needed to pass the values of the environment variables within the JSON body.\n\n On a successful creation request, the organizations API responds with a message similar\n to the following: \n\n ```carbon\n {\n \"name\": \"organizations/\u003cvar translate=\"no\"\u003eorg_name\u003c/var\u003e/operations/\u003cvar translate=\"no\"\u003eLONG_RUNNING_OPERATION_ID\u003c/var\u003e\",\n \"metadata\": {\n \"@type\": \"type.googleapis.com/google.cloud.apigee.v1.OperationMetadata\",\n \"operationType\": \"INSERT\",\n \"targetResourceName\": \"organizations/\u003cvar translate=\"no\"\u003eorg_name\u003c/var\u003e\",\n \"state\": \"IN_PROGRESS\"\n }\n }\n ```\n\n Where:\n - \u003cvar translate=\"no\"\u003eLONG_RUNNING_OPERATION_ID\u003c/var\u003e 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).\n - \u003cvar translate=\"no\"\u003eorg_name\u003c/var\u003e is the ID of your new organization that is currently being created.\n\n As the `state` property in the response indicates, Apigee has started to create\n the new organization, so\n its state is `IN_PROGRESS`. This process can take several minutes.\n\n If you get an error, see [Troubleshooting organization creation](#errors).\n4. Save the long-running operation ID to an environment variable. It will be useful for future management tasks. \n\n ### Syntax\n\n ```\n export LONG_RUNNING_OPERATION_ID=LONG_RUNNING_OPERATION_ID\n ```\n\n ### Example\n\n ```\n export LONG_RUNNING_OPERATION_ID=6abc8a72-46de-f9da-bcfe-70d9ab347e4f\n ```\n5. 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: \n\n ```\n curl -H \"Authorization: Bearer $TOKEN\" \\\n \"https://apigee.googleapis.com/v1/organizations/$ORG_NAME/operations/$LONG_RUNNING_OPERATION_ID\"\n ```\n\n The following examples show possible responses to this request: \n\n ### IN_PROGRESS\n\n If Apigee is still creating the organization, Apigee responds with a status of\n `IN_PROGRESS`. For example: \n\n ```carbon\n {\n \"name\": \"organizations/\u003cvar translate=\"no\"\u003eORG_NAME\u003c/var\u003e/operations/\u003cvar translate=\"no\"\u003eLONG_RUNNING_OPERATION_ID\u003c/var\u003e\",\n \"metadata\": {\n \"@type\": \"type.googleapis.com/google.cloud.apigee.v1.OperationMetadata\",\n \"operationType\": \"INSERT\",\n \"targetResourceName\": \"organizations/\u003cvar translate=\"no\"\u003eORG_NAME\u003c/var\u003e\",\n \"state\": \"IN_PROGRESS\"\n }\n }\n ```\n\n You should wait a little longer before attempting to verify that the creation process\n is complete.\n\n ### FINISHED\n\n When the organization has been provisioned, the state of the long-running operation is\n `FINISHED`. For example: \n\n ```carbon\n {\n \"name\": \"organizations/\u003cvar translate=\"no\"\u003eORG_NAME\u003c/var\u003e/operations/\u003cvar translate=\"no\"\u003eLONG_RUNNING_OPERATION_ID\u003c/var\u003e\",\n \"metadata\": {\n \"@type\": \"type.googleapis.com/google.cloud.apigee.v1.OperationMetadata\",\n \"operationType\": \"INSERT\",\n \"targetResourceName\": \"organizations/\u003cvar translate=\"no\"\u003eORG_NAME\u003c/var\u003e\",\n \"state\": \"FINISHED\"\n },\n \"done\": true,\n \"response\": {\n \"@type\": \"type.googleapis.com/google.cloud.apigee.v1.Organization\",\n \"name\": \"\u003cvar translate=\"no\"\u003eORG_NAME\u003c/var\u003e\",\n \"description\": \"\",\n \"createdAt\": \"1626237148461\",\n \"lastModifiedAt\": \"1626237149384\",\n \"properties\": {\n \"property\": [\n {\n \"name\": \"features.hybrid.enabled\",\n \"value\": \"true\"\n },\n {\n \"name\": \"features.mart.connect.enabled\",\n \"value\": \"true\"\n }\n ]\n },\n \"analyticsRegion\": \"\u003cvar translate=\"no\"\u003eANALYTICS_REGION\u003c/var\u003e\",\n \"runtimeType\": \"HYBRID\",\n \"subscriptionType\": \"TRIAL\",\n \"state\": \"ACTIVE\",\n \"billingType\": \"EVALUATION\",\n \"expiresAt\": \"1631421073171\",\n \"addonsConfig\": {\n \"advancedApiOpsConfig\": {},\n \"integrationConfig\": {},\n \"monetizationConfig\": {}\n }\n }\n }\n ```\n6. You can use the Apigee organizations API to retrieve information about an organization after\n it is created.\n For example:\n\n ```\n curl -H \"Authorization: Bearer $TOKEN\" \\\n \"https://apigee.googleapis.com/v1/organizations/$ORG_NAME\"\n ```\n\n The response to your request contains details about the specified organization in JSON\n format. \n\n ```text\n {\n \"name\": \"apigee-example\",\n \"createdAt\": \"1626237148461\",\n \"lastModifiedAt\": \"1626237149384\",\n \"properties\": {\n \"property\": [\n {\n \"name\": \"features.hybrid.enabled\",\n \"value\": \"true\"\n },\n {\n \"name\": \"features.mart.connect.enabled\",\n \"value\": \"true\"\n }\n ]\n },\n \"analyticsRegion\": \"us-west1\",\n \"runtimeType\": \"HYBRID\",\n \"subscriptionType\": \"TRIAL\",\n \"projectId\": \"apigee-example\",\n \"state\": \"ACTIVE\",\n \"billingType\": \"EVALUATION\",\n \"expiresAt\": \"1631421073171\",\n \"addonsConfig\": {\n \"advancedApiOpsConfig\": {},\n \"integrationConfig\": {},\n \"monetizationConfig\": {}\n }\n }\n ```\n\nTroubleshooting organization creation\n-------------------------------------\n\nWhen you create an organization with the [Create organizations API](/apigee/docs/reference/apis/apigee/rest/v1/organizations/create), you might get an error\nresponse. Responses look like the following: \n\n```\n{\n \"error\": {\n \"code\": HTTP_error_code,\n \"message\": \"short_error_message\",\n \"status\": \"high_level_error_type\",\n \"details\": [\n {\n \"@type\": \"specific_error_type\",\n \"detail\": \"expanded_error_description\"\n }\n ]\n }\n}\n```\n\nThe following table lists errors you might receive and potential resolutions when you try to create\na new organization:\n\nNext step\n---------\n\n\nGo to Step 3: [Create an environment group](/apigee/docs/hybrid/v1.9/precog-add-environment)."]]