Step 4: Create an organization

You've created a GCP account and project and enabled the APIs. Now you can create your organization.

Prerequisite

To create an organization, you must either:

  • Be in a trial
  • Have a paid account

If neither of these is true, then you must contact Apigee Sales before you can continue.

To create a new organization and provision it:

  1. On the command line, get your gcloud authentication credentials, as the following example shows:

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

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

    echo $TOKEN

    This should print an encoded string to stdout.

    For more information, see gcloud command-line tool overview.

  2. Send an authenticated POST request to the Create Organizations API.

    The following example shows the request structure that creates an organization:

    curl -H "Authorization: Bearer $TOKEN" -X POST -H "content-type:application/json" \
      -d '{
        "name":"proposed_org_ID",
        "display_name":"display_name",
        "description":"organization_description",
        "analyticsRegion":"analytics_region"
      }' \
      "https://apigee.googleapis.com/v1/organizations?parent=projects/project_ID"

    Where:

    • (Required) proposed_org_ID is the programmatic ID that you want for your hybrid-enabled organization. For example, my-hybrid-org.

      Apigee recommends that you use the same ID as the GCP project ID that you created in Step 2: Create a GCP project, but you can use another ID if you want.

    • (Required) analytics_region is the primary region for analytics data storage. Choose one of the following:
      asia-east1 australia-southeast1 us-central1
      asia-northeast1 europe-west1 us-east1
      asia-southeast1 europe-west2 us-east4
      us-west1

      We provide this option so that you can choose a region that is geographically close or if your organization has other storage requirements.

    • (Required) project_ID is the GCP project that you want bound to your new hybrid-enabled organization. This is the ID that Google generated for you in Step 2: Create a GCP project.
    • (Optional) display_name is the user-friendly name of your organization. This value does not need to be unique, and can include spaces and special characters. For example, "My Hybrid Organization".
    • (Optional) organization_description is information about the organization that you'd like to use as a reminder of its purpose. For example, "My first organization".

    On a successful creation request, the Organizations API should respond with a message similar to the following:

    {
      "name": "organizations/organization_ID/operations/long_running_operation_ID",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
        "operationType": "INSERT",
        "targetResourceName": "organizations/organization_ID",
        "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 organizatioin creation request (described later).
    • organization_ID 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 it's state is IN_PROGRESS. This process can take several minutes.

    If you get an error, see Troubleshooting organization creation.

  3. You can check the status of the long-running operation whose ID Apigee returned on your initial creation request. To do this, use the Operations API, as the following example shows:
    curl -H "Authorization: Bearer $TOKEN" \
      "https://apigee.googleapis.com/v1/organizations/organization_ID/operations/long_running_operation_ID"

    The following examples show possible responses to this request:

    FINISHED

    When the organization has been provisioned, the state of the long-running operation is FINISHED, as the following example shows:

    {
        "operations": [
          {
            "name": "organizations/organization_ID/operations/long_running_operation_ID",
            "metadata": {
              "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
              "operationType": "INSERT",
              "targetResourceName": "organizations/organization_ID",
              "state": "FINISHED"
            },
            "done": true,
            "response": {
              "@type": "type.googleapis.com/google.cloud.apigee.v1.Organization",
              "name": "organization_ID",
              "createdAt": "1572550611",
              "lastModifiedAt": "1572550611",
              "displayName": "display_name"
              "description": "description"
              "properties": {
                "property": [
                  {
                    "name": "features.hybrid.enabled",
                    "value": "true"
                  }
                ]
              },
              "analyticsRegion": "us-east1"
            }
          }
        ]
      }

    If you did not enter a description, then that field will not appear in the response.

    Congratulations! You have created a new organization and it is ready for you to use. You can continue to Step 5: Add an environment.

    IN_PROGRESS

    If Apigee is still creating the organization, Apigee responds with a status of IN_PROGRESS, as the following example shows:

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

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

Troubleshooting organization creation

When you create an organization with the Create 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 example shows a response to a common error—the organization ID contains illegal characters (upper case characters are not allowed in organization IDs):

{
  "error": {
    "code": 400,
    "message": "invalid Organization ID \"MY-ORG\": \"MY-ORG\" is an invalid Organization ID",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.DebugInfo",
        "detail": "[ORIGINAL ERROR] generic::invalid_argument: invalid Organization ID \"MY-ORG\":
          \"My-ORG\" is an invalid Organization ID [google.rpc.error_details_ext]
          { message: \"invalid Organization ID \\\"MY-ORG\\\": \\\"MY-ORG\\\" is an invalid
          Organization ID\" }"
      }
    ]
  }
}

In this case, you could rename the organization with lower-case letters and resend your request.

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 upper-case letters or any special characters other than hyphens. It must contain only lower-case letters, numbers, and/or hypens. 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 GCP project (that you created in Step 2: Create a GCP project) has not yet been hybrid enabled. This could indicate an issue with your billing or some other error related to your GCP 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 the procedure above.
409 Organization already exists You tried to create more than one organization for the GCP project. You can only create one organization per project.
409 Org proposed_organization_ID 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.

Get organization information

You can get a list of all organizations that your account has access to, or you can get details about a specific organization by its ID. To perform these actions, you use the Organizations API.

List organizations

To get a list of all organizations:

Send a GET request (with no body) to the following List Organizations API endpoint:

https://apigee.googleapis.com/v1/organizations

For example:

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

The response to your request contains an array of all hybrid-enabled organizations that you have access to, in JSON format.

The following example shows a response with a single organization, "my-org-42":

{
  "organizations": [
    {
      "organization": "my-org-42",
      "projectIds": [
        "my-project"
      ]
    }
  ]
}

Get details

To get details about a single organization:

Send a GET request (with no body) to the following Get Organizations API endpoint:

https://apigee.googleapis.com/v1/organizations/organization_ID

The following example gets details about the "my-org-42" organization:

curl -H "Authorization: Bearer $TOKEN"
  "https://apigee.googleapis.com/v1/organizations/my-org-42"

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

The following example shows a response with details about the "my-org-42" organization:

{
  "name": "my-org-42",
  "createdAt": "1572550611",
  "lastModifiedAt": "1572550611",
  "environments": [
    "my-environment"
  ],
  "analyticsRegion": "us-east1"
}

Next Step

1 2 3 4 NEXT: (5) Add an environment