Create and manage Apigee Spaces

This page applies to Apigeeand 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:

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, 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

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
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.
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

In the Google Cloud console, go to the IAM page.
Go to IAM
Select the project.
Click Grant access .
In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
Click Select a role , then search for the role.
To grant additional roles, click Add another role and add each additional role.
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.

Create a Space in your Apigee organization using the Apigee console or the API, as described in the following sections.

Apigee console

To create a Space using the Apigee UI:

In the Apigee UI in Cloud console , go to the Spacespage.
Go to Spaces
Click Create. The Add Space Detailspanel opens.
In the Namefield, enter a unique identifier for the Space. The name must be fewer than 63 characters long, start with a lowercase letter, and contain only lowercase characters. For full naming requirements, see AIP-122: Resource names .
(Optional) In the Display Namefield, enter a human-readable label for the Space.
Click Add.

After creation, organization members will see the Space as an available parameter when creating API resources.

Apigee API

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 unique identifier of the Space. The name must be fewer than 63 characters long, start with a lowercase letter, and contain only lowercase characters. For full naming requirements, see AIP-122: Resource names .
DISPLAY_NAME is the human-readable name of the Space as it appears in the Apigee UI in Cloud console .

Manage members and roles in a Space

After you create a Space, you can add team members to the Space and assign the IAM roles required to create and manage API resources.

Add an organization member to a Space

To perform this task, you need the apigee.spaces.setIamPolicy permission.

Note:The IAM role apigee.spaceContentEditor contains many of the permissions required to manage Space resources. We recommend that you grant this role, at a minimum, to Space users. However, you may need to grant additional roles to users to perform specific tasks. For more information, see IAM permission hierarchy in Spaces .

Apigee console

To grant a member access to a Space using the Apigee UI:

In the Apigee UI in Cloud console , go to the Spacespage.
Click the name of the Space you want to manage.
In the Access detailssection, click Grant access.
In the Add membersfield, enter the email addresses of the users or groups you want to add.
Under Assign role, select either Content Editoror Content Viewer.
Click Add.

Note:If you have the resourcemanager.projects.setIamPolicy permission, the system automatically grants each new member the Apigee Space Console Userrole at the project level, allowing them to access the Apigee UI in Cloud console . If you do not have this permission, you will see a warning, and a project administrator must manually grant this role to the users.

Apigee API

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 your Apigee organization.
SPACE_NAME is the name of the Space.
USER_EMAIL is the email address of the user you are adding to the Space. To add a Google Group instead of a single user, change the prefix from user: to group: and provide the group's email address.
IAM_ROLE is the name of the IAM role you are assigning to the member.

Remove members from a Space

To perform this task, you need the apigee.spaces.setIamPolicy permission.

Apigee console

To remove a member from a Space using the Apigee UI:

In the Apigee UI in Cloud console , go to the Spacespage and click the name of the Space.
In the Access detailstable, select the checkbox next to one or more members you want to remove.
Click Remove access.
In the confirmation dialog, click Confirm.

Apigee API

To remove members from a Space, set a new IAM policy for the space with the revised list of members using the setIamPolicy method. Using this method creates a new IAM policy that replaces the existing policy.

For example, to update the members of the blueteam 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", 
 "user:user-a@acme.com", 
 "user:user-b@acme.com", 
 "user:user-c@acme.com" 
  
 ] 
  
 } 
  
 ] 
 }

To remove user-b@acme.comfrom 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" 
 , 
  
 "user:user-a@acme.com" 
 , 
  
 "user: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.

Apigee console

To view all Spaces, go to the Spacespage in the Apigee UI in Cloud console .

Go to Spaces

The Spaces table lists all Spaces in your organization, including their Name, Display Name, and total number of Members.

Apigee API

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 your Apigee organization.

Get Space details

To perform this task, you need the apigee.spaces.get permission.

Apigee console

To view Space details in the Apigee UI:

In the Apigee UI in Cloud console , go to the Spacespage.
Click the name of the Space you want to view. The details page displays the Name, Display Name, access details, and the Memberslist.

Apigee API

To get the details of a Space, use the following command:

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 your Apigee organization.
SPACE_NAME is the name of the Space.

Update a Space

To perform this task, you need the apigee.spaces.update permission.

You can modify the Display Nameof an existing Space. The unique Name cannot be changed after creation.

Apigee console

To update a Space in the Apigee UI:

In the Apigee UI in Cloud console , go to the Spacespage and click the name of the Space you want to update.
Click the editbutton (pencil icon) next to the "Space details" heading.
Modify the Display Nameas needed.
Click Save.

Apigee API

To update a Space using the API, 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 your Apigee organization.
SPACE_NAME is the name of the Space.
DISPLAY_NAME is the new display name for the Space.

Delete a Space

To perform this task, you need the apigee.spaces.delete permission.

Apigee console

To delete a Space using the Apigee UI:

In the Apigee UI in Cloud console , go to the Spacespage.
Click Deletein the row of the Space you want to delete.
In the confirmation dialog, type the exact name of the Space to confirm.
Click Delete.

Apigee API

Before deleting a Space using the API, make sure that all the resources in the Space have been deleted or moved.

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

Where:

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

If you attempt to delete a Space that still contains active resources, the deletion will fail with a response similar to the following:

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

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

What's next

Learn more about Apigee Spaces .
Learn to Manage API resources with Apigee Spaces .
Review Identity and Access Management (IAM) documentation .

Create and manage Apigee Spaces Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Required roles and permissions

Check for the roles

Grant the roles

Create a Space

Apigee console

Apigee API

Manage members and roles in a Space

Add an organization member to a Space

Apigee console

Apigee API

Remove members from a Space

Apigee console

Apigee API

List all Spaces in an organization

Apigee console

Apigee API

Get Space details

Apigee console

Apigee API

Update a Space

Apigee console

Apigee API

Delete a Space

Apigee console

Apigee API

What's next

Create and manage Apigee Spaces