This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

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

This guide outlines the steps required to:

• Create a Space
• Manage members and roles in a Space
• List all spaces in an organization
• Get Space details
• Update a Space
• Delete a Space

For more on the benefits of using Apigee Spaces to manage your API resources, seeApigee 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, seeIntroduction to provisioning.
• Get your authentication credentials. Before running commands to create and manage Spaces on the command line, get yourgcloud authentication credentials using the following command:

  exportTOKEN=$(gcloudauthprint-access-token)

Required roles and permissions

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

Create a Space

To perform this task, you need theapigee.spaces.create permission. This permission is included in theApigee 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 theApigee UI in Cloud console. If no display name is provided, the Space name will be used as the display name.
Note: Space names cannot exceed 32 characters andmust follow the naming requirements defined inAIP 122: Resource names.

For example, the following command creates a Space namedred in theacme 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 theApigee UI in Cloud console willsee 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.

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 theapigee.spaces.setIamPolicy permission. This permission is included in theApigee Organization Admin role.

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

curl-XPOST-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 themy-email@acme.com user to thered Space in theacme organization, and grants the IAM roleapigee.spaceContentEditor:

curl-XPOST-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 thesetIamPolicy 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-XPOST-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 theacme-team@acme.com group to thered Space in theacme organization and grants theapigee.spaceContentEditor role to the group:

curl-XPOST-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 inAdd an organization member to a Space, the IAM roleapigee.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 theapigee.spaces.getIamPolicy permission. This permission is included in theApigee 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 thered Space in theacme 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 theapigee.spaceContentEditor role to space members, in this case, members of the groupred-team@acme.com

Note that the members of thered team are the only organization members granted access to thered 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 asteam-blue@acme.com try to access an API proxy created under thered 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 thesetIamPolicy method will create a new IAM policy for the space, with roles and members adjusted accordingly.

For example, to update the members of theblue 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 removeuser-b@acme.com from the Space, use the following command:

curl-XPOST-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 includeuser-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 theapigee.spaces.list permission. This permission is included in theApigee 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"

WhereORG_NAME is the name of the Apigee organization.

For example, the following command lists all the Spaces in theacme 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 theapigee.spaces.get permission.This permission is included in theApigee 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 thered Space in theacme 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 theapigee.spaces.update permission.This permission is included in theApigee 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 thered Space in theacme 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 theapigee.spaces.delete permission.This permission is included in theApigee Organization Admin role. Before deletinga 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 thered Space in theacme 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

• Learn more aboutApigee Spaces.
• Learn toManage API resources with Apigee Spaces.
• Review Identity and Access Management (IAM)documentation.