Create and manage Apigee Spaces

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

This page describes how to create Apigee Spaces in your Apigee organization to manage Identity and Access Management (IAM) policies for Apigee API resources at scale.

This guide outlines the steps required to:

For more on the benefits of using Apigee Spaces to manage your API resources, see Apigee Spaces.

Before you begin

Before getting started with Spaces:

  • Provision Apigee. Confirm that the Apigee Subscription or Pay-as-you-go organization you want to use is provisioned. For more information on the steps required to provision Apigee, see Introduction to provisioning.
  • Get your authentication credentials. Before running commands to create and manage Spaces on the command line, get your gcloud authentication credentials using the following command: 
    export TOKEN=$(gcloud auth print-access-token)

Required roles and permissions

Make sure that you have the following role or roles on the project: Apigee > Apigee Organization Admin

Check for the roles

  1. In the Google Cloud console, go to the IAM page.

    Go to IAM
  2. Select the project.

  3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

  4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

Grant the roles

  1. In the Google Cloud console, go to the IAM page.

    Go to IAM
  2. Select the project.
  3. Click Grant access.

  4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

  5. In the Select a role list, select a role.
  6. To grant additional roles, click Add another role and add each additional role.
  7. Click Save.

Create a Space

To perform this task, you need the apigee.spaces.create permission. This permission is included in the Apigee Organization Admin role.

To create a Space in your Apigee organization, use the following command: 

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    "https://apigee.googleapis.com/v1/organizations/ORG_NAME/spaces" \
    --data-raw '{
       "name":"SPACE_NAME",
       "displayName":"DISPLAY_NAME",
    }'

Where:

  • ORG_NAME is the name of your Apigee organization.
  • SPACE_NAME is the name and ID of the Space.
  • DISPLAY_NAME is the name of the Space as it should appear in the Apigee UI in Cloud console. If no display name is provided, the Space name will be used as the display name.

For example, the following command creates a Space named red in the acme organization: 

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/acme/spaces \
    --data-raw '{
       "name":"red",
       "displayName":"Red",
    }'

Once you create a Space in your organization, organization members using the Apigee UI in Cloud console will see the Space as an available parameter when creating API resources in the UI. In addition, when viewing lists of API proxies, API products and shared flows in the UI, the Space will appear as an attribute for API resources assigned to that Space.

Spaces.

Manage members and roles in a Space

Once you have created a Space, you can add team members to the Space and assign the IAM roles required to create and manage API resources in the Space. Apigee users can only create and manage resources in Spaces where they are team members granted the appropriate permissions. Because IAM access control is granted at the Spaces level, organization members are not able to access or manage Apigee API resources belonging to the Space unless they are specifically added to the Space. For an overview of the IAM roles and permissions required to manage Space resources, see Create and manage Space resources.

Add an organization member to a Space

When an organization member is added to a Space, an IAM policy binding is created for the space that takes two arguments:

  • The list of Space members
  • The role or list of roles granted to the members

To perform this task, you need the apigee.spaces.setIamPolicy permission. This permission is included in the Apigee Organization Admin role.

To add an organization member to a Space and assign an IAM role, use the following command: 

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-type: application/json" \
    "https://apigee.googleapis.com/v1/organizations/ORG_NAME/spaces/SPACE_NAME:setIamPolicy" -d \
      '{
        "policy":{
          "bindings":[
            {
              "members": ["user:USER_EMAIL"],
              "role": "roles/IAM_ROLE"
            }
          ]
        }
      }'

Where:

  • ORG_NAME is the name of the Apigee organization.
  • SPACE_NAME is the name of the Space.
  • USER_EMAIL is the email address of a user you are adding to the Space.
  • IAM_ROLE is the name of the IAM role you are assigning to the user as a Space member.

For example, this command adds the my-email@acme.com user to the red Space in the acme organization, and grants the IAM role apigee.spaceContentEditor: 

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-type: application/json" \
    "https://apigee.googleapis.com/v1/organizations/acme/spaces/red:setIamPolicy" -d \
      '{ 
        "policy":{
          "bindings":[
            {
              "members": ["user:my-email@acme.com"],
              "role": "roles/apigee.spaceContentEditor"
            }
          ]
        }
      }'

Additional roles and permissions can be added for Space members by updating the IAM policy for the Space. To update the IAM policy for a Space, use the setIamPolicy method described in this section, using the revised list of desired roles and permissions. This will create a new IAM policy for the space, with roles and permissions adjusted accordingly.

Add a team of members to a Space

Alternatively, you can add a team of members to a Space and assign an IAM role or roles. To add a team of members to a Space and assign an IAM role, use the following command: 

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-type: application/json" \
   "https://apigee.googleapis.com/v1/organizations/ORG_NAME/spaces/SPACE_NAME:setIamPolicy" -d \
     '{
       "policy":{
         "bindings":[
           {
             "members": ["group:GROUP_EMAIL"],
             "role": "roles/IAM_ROLE"
           }
         ]
       }
     }'

Where:

  • ORG_NAME is the name of the Apigee organization.
  • SPACE_NAME is the name of the Space.
  • GROUP_EMAIL is the email address of a group you are adding to the Space.
  • IAM_ROLE is the name of the IAM role you are assigning to the team as a Space member.

For example, this command adds the acme-team@acme.com group to the red Space in the acme organization and grants the apigee.spaceContentEditor role to the group: 

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-type: application/json" \
   "https://apigee.googleapis.com/v1/organizations/acme/spaces/red:setIamPolicy" -d \
     '{ 
       "policy":{
         "bindings":[
           {
             "members": ["group:red-team@acme.com"],
             "role": "roles/apigee.spaceContentEditor"
           }
         ]
       }
     }'

As noted in Add an organization member to a Space, the IAM role apigee.spaceContentEditor contains many of the permissions required to manage Space resources. However, you may need to grant additional roles to users to perform specific tasks.

Verify the Spaces IAM policy assignment

To perform this task, you need the apigee.spaces.getIamPolicy permission. This permission is included in the Apigee Organization Admin role.

To verify that the IAM policy is set correctly for the space, use the following command: 

curl -X GET -H "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/ORG_NAME/spaces/SPACE_NAME:getIamPolicy"

Where:

  • ORG_NAME is the name of the Apigee organization.
  • SPACE_NAME is the name of the Space.

For example, the following command is used to confirm that the IAM policy is set correctly for the red Space in the acme organization: 

curl -X GET -H "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/acme/spaces/red:getIamPolicy"

The output of the command returns the current IAM policy for the space, and should look something like this: 

{
  "version": "0",
  "bindings": [
    {
      "role": "roles/apigee.spaceContentEditor",
      "members": [
        "group:red-team@acme.com"
      ]
    }
  ]
}

In this example, the IAM policy for the space grants the apigee.spaceContentEditor role to space members, in this case, members of the group red-team@acme.com

Note that the members of the red team are the only organization members granted access to the red Space. This means that only the red team members can create and manage API resources in the red Space. If members of another organization team, such as team-blue@acme.com try to access an API proxy created under the red Space, they will see the following error: 

{
  "error": {
    "code": 403,
    "message": "Permission denied on resource \"organizations\/acme\/apis\/proxy-1\" (or it may not exist).",
    "status": "PERMISSION_DENIED"
  }
}

Remove members from a Space

To remove members, or a group of members, from a Space, you will need to set a new IAM policy for the space, with a revised list of members or groups. Using the setIamPolicy method will create a new IAM policy for the space, with roles and members adjusted accordingly.

For example, to update the members of the blue team Space, you can first check the current IAM policy using the following command: 

curl -X GET -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/acme/spaces/blue:getIamPolicy"

The output of the command returns the current IAM policy for the space, and should look something like this: 

{
  "version": "0",
  "bindings": [
    {
      "role": "roles/apigee.spaceContentEditor",
      "members": [
        "group: blue-team@acme.com", 
        "users: user-a@acme.com, user-b@acme.com, user-c@acme.com"
      ]
    }
  ]
}

To remove user-b@acme.com from the Space, use the following command: 

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-type: application/json" \
  "https://apigee.googleapis.com/v1/organizations/acme/spaces/blue:setIamPolicy" -d \
    '{ 
      "policy":{
        "bindings":[
          {
            "members": [
              "group:blue-team@acme.com",
              "users: user-a@acme.com, user-c@acme.com"
            ]  
            "role": "roles/apigee.spaceContentEditor"
          }
        ]
      }
    }'

The new IAM policy for the Space will no longer include user-b@acme.com.

To remove a member from a group included in a Space, first remove the member from the group and then rerun the setIamPolicy command to update the IAM policy for the Space with the correct membership for the group email alias.

List all Spaces in an organization

To perform this task, you need the apigee.spaces.list permission. This permission is included in the Apigee Organization Admin role.

To list all the Spaces in an Apigee organization, use the following command: 

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

Where ORG_NAME is the name of the Apigee organization.

For example, the following command lists all the Spaces in the acme organization: 

curl -X GET -H "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/acme/spaces"

This command returns something like the following: 

  {
    "spaces": [
        {
            "name": "red",
            "createTime": "2024-08-02T23:26:03.001512Z",
            "updateTime": "2024-08-02T23:26:03.001512Z"
        },
        {
            "name": "blue",
            "createTime": "2024-08-02T00:34:54.159331Z",
            "updateTime": "2024-08-02T00:34:54.159331Z"
      }
      ]
  }

Get Space details

To perform this task, you will need the apigee.spaces.get permission. This permission is included in the Apigee Organization Admin role.

Use the following command to get Space details: 

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

Where:

  • ORG_NAME is the name of the Apigee organization.
  • SPACE_NAME is the name of the Space.

For example, the following command gets details about the red Space in the acme organization: 

curl -X GET -H "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/acme/spaces/red"

This command returns something like the following: 

  {
      "name": "red",
      "createTime": "2024-08-02T23:26:03.001512Z",
      "updateTime": "2024-08-02T23:26:03.001512Z"
  }

Update a Space

To perform this task, you need the apigee.spaces.update permission. This permission is included in the Apigee Organization Admin role.

To update a Space in your Apigee organization, use the following command: 

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    "https://apigee.googleapis.com/v1/organizations/ORG_NAME/spaces/SPACE_NAME" \
      --data-raw '{
        "displayName":"DISPLAY_NAME"
      }'

Where:

  • ORG_NAME is the name of the Apigee organization.
  • SPACE_NAME is the name and ID of the Space.
  • DISPLAY_NAME is the new display name for the Space.

For example, the following command updates the display name of the red Space in the acme organization: 

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    "https://apigee.googleapis.com/v1/organizations/acme/spaces/red" -d \
    '{
      "displayName": "Red team space"
    }'

Delete a Space

To perform this task, you need the apigee.spaces.delete permission. This permission is included in the Apigee Organization Admin role. Before deleting a Space, make sure that all the resources in the Space have also been deleted.

To delete a Space in your Apigee organization, use the following command: 

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

For example, the following command deletes the red Space in the acme organization: 

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/acme/spaces/red"

If you attempt to delete a Space with active resources still associated with it, you will see the following error: 

{
  "error": {
    "code": 400,
    "message": "Space \"red\" has resources associated with it. Please delete the resources before deleting the space.",
    "status": "FAILED_PRECONDITION"
  }
}

To resolve the error, delete or move the resources in the Space before attempting to delete the Space.

What's next