Manage GCP API Gateway IAM Bindings

The gcp:apigateway/apiConfigIamBinding:ApiConfigIamBinding resource, part of the Pulumi GCP provider, manages IAM role bindings for API Gateway ApiConfig resources. It controls which identities can access or manage API configurations. This guide focuses on two capabilities: binding multiple members to a role and adding individual members incrementally.

IAM bindings attach to existing API Gateway ApiConfig resources and reference Google Cloud identities. The examples are intentionally small. Combine them with your own API Gateway infrastructure and identity management strategy.

Grant a role to multiple members at once

When multiple users or service accounts need the same level of access, binding them to a role in a single resource simplifies management.

import * as pulumi from "@pulumi/pulumi";
import * as gcp from "@pulumi/gcp";

const binding = new gcp.apigateway.ApiConfigIamBinding("binding", {
    api: apiCfg.api,
    apiConfig: apiCfg.apiConfigId,
    role: "roles/apigateway.viewer",
    members: ["user:jane@example.com"],
});

import pulumi
import pulumi_gcp as gcp

binding = gcp.apigateway.ApiConfigIamBinding("binding",
    api=api_cfg["api"],
    api_config=api_cfg["apiConfigId"],
    role="roles/apigateway.viewer",
    members=["user:jane@example.com"])

package main

import (
	"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/apigateway"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := apigateway.NewApiConfigIamBinding(ctx, "binding", &apigateway.ApiConfigIamBindingArgs{
			Api:       pulumi.Any(apiCfg.Api),
			ApiConfig: pulumi.Any(apiCfg.ApiConfigId),
			Role:      pulumi.String("roles/apigateway.viewer"),
			Members: pulumi.StringArray{
				pulumi.String("user:jane@example.com"),
			},
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Gcp = Pulumi.Gcp;

return await Deployment.RunAsync(() => 
{
    var binding = new Gcp.ApiGateway.ApiConfigIamBinding("binding", new()
    {
        Api = apiCfg.Api,
        ApiConfig = apiCfg.ApiConfigId,
        Role = "roles/apigateway.viewer",
        Members = new[]
        {
            "user:jane@example.com",
        },
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.apigateway.ApiConfigIamBinding;
import com.pulumi.gcp.apigateway.ApiConfigIamBindingArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var binding = new ApiConfigIamBinding("binding", ApiConfigIamBindingArgs.builder()
            .api(apiCfg.api())
            .apiConfig(apiCfg.apiConfigId())
            .role("roles/apigateway.viewer")
            .members("user:jane@example.com")
            .build());

    }
}

resources:
  binding:
    type: gcp:apigateway:ApiConfigIamBinding
    properties:
      api: ${apiCfg.api}
      apiConfig: ${apiCfg.apiConfigId}
      role: roles/apigateway.viewer
      members:
        - user:jane@example.com

The ApiConfigIamBinding resource is authoritative for the specified role. The members array lists all identities that should have this role; any existing members not in the list are removed. The role property specifies the permission level (e.g., roles/apigateway.viewer), and api and apiConfig identify the target resource.

Add a single member to a role incrementally

Teams managing access through multiple stacks or needing to add members without affecting existing bindings use the non-authoritative member resource.

import * as pulumi from "@pulumi/pulumi";
import * as gcp from "@pulumi/gcp";

const member = new gcp.apigateway.ApiConfigIamMember("member", {
    api: apiCfg.api,
    apiConfig: apiCfg.apiConfigId,
    role: "roles/apigateway.viewer",
    member: "user:jane@example.com",
});

import pulumi
import pulumi_gcp as gcp

member = gcp.apigateway.ApiConfigIamMember("member",
    api=api_cfg["api"],
    api_config=api_cfg["apiConfigId"],
    role="roles/apigateway.viewer",
    member="user:jane@example.com")

package main

import (
	"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/apigateway"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := apigateway.NewApiConfigIamMember(ctx, "member", &apigateway.ApiConfigIamMemberArgs{
			Api:       pulumi.Any(apiCfg.Api),
			ApiConfig: pulumi.Any(apiCfg.ApiConfigId),
			Role:      pulumi.String("roles/apigateway.viewer"),
			Member:    pulumi.String("user:jane@example.com"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Gcp = Pulumi.Gcp;

return await Deployment.RunAsync(() => 
{
    var member = new Gcp.ApiGateway.ApiConfigIamMember("member", new()
    {
        Api = apiCfg.Api,
        ApiConfig = apiCfg.ApiConfigId,
        Role = "roles/apigateway.viewer",
        Member = "user:jane@example.com",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.apigateway.ApiConfigIamMember;
import com.pulumi.gcp.apigateway.ApiConfigIamMemberArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var member = new ApiConfigIamMember("member", ApiConfigIamMemberArgs.builder()
            .api(apiCfg.api())
            .apiConfig(apiCfg.apiConfigId())
            .role("roles/apigateway.viewer")
            .member("user:jane@example.com")
            .build());

    }
}

resources:
  member:
    type: gcp:apigateway:ApiConfigIamMember
    properties:
      api: ${apiCfg.api}
      apiConfig: ${apiCfg.apiConfigId}
      role: roles/apigateway.viewer
      member: user:jane@example.com

The ApiConfigIamMember resource adds a single identity to a role without replacing existing members. Use member (singular) instead of members (plural) to specify one identity. This approach works well when different teams or stacks manage different users’ access to the same API config.

Beyond these examples

These snippets focus on specific IAM binding features: role binding for multiple members and incremental member addition. They’re intentionally minimal rather than full access control configurations.

The examples reference pre-existing infrastructure such as API Gateway API and ApiConfig resources. They focus on configuring IAM bindings rather than provisioning the underlying API Gateway resources.

To keep things focused, common IAM patterns are omitted, including:

Conditional IAM bindings (condition property)
Full policy replacement (ApiConfigIamPolicy)
Custom role definitions
Federated identity principals

These omissions are intentional: the goal is to illustrate how each IAM binding approach is wired, not provide drop-in access control modules. See the ApiConfigIamBinding resource reference for all available configuration options.

Let's manage GCP API Gateway IAM Bindings

Get started with Pulumi Cloud, then follow our quick setup guide to deploy this infrastructure.

Try Pulumi Cloud for FREE

Frequently Asked Questions

Resource Selection & Compatibility

What's the difference between ApiConfigIamPolicy, ApiConfigIamBinding, and ApiConfigIamMember?

gcp.apigateway.ApiConfigIamPolicy is authoritative and replaces the entire IAM policy. gcp.apigateway.ApiConfigIamBinding is authoritative for a specific role, preserving other roles. gcp.apigateway.ApiConfigIamMember is non-authoritative, adding members without affecting other members for the same role.

Can I use these IAM resources together?

gcp.apigateway.ApiConfigIamPolicy cannot be used with gcp.apigateway.ApiConfigIamBinding or gcp.apigateway.ApiConfigIamMember as they will conflict. However, gcp.apigateway.ApiConfigIamBinding and gcp.apigateway.ApiConfigIamMember can be used together only if they grant different roles.

Why are my IAM resources fighting over the policy?

Mixing gcp.apigateway.ApiConfigIamPolicy with gcp.apigateway.ApiConfigIamBinding or gcp.apigateway.ApiConfigIamMember causes conflicts because Policy is authoritative and overwrites changes from the other resources. Use Policy alone, or use Binding/Member together without Policy.

Configuration & Formats

How do I specify custom roles?

Custom roles must use the full format [projects|organizations]/{parent-name}/roles/{role-name}, for example projects/my-project/roles/my-custom-role or organizations/my-org/roles/my-custom-role.

What member identity formats are supported?

The members property supports multiple formats:

allUsers or allAuthenticatedUsers for public/authenticated access
user:{email}, serviceAccount:{email}, group:{email} for specific identities
domain:{domain} for G Suite domains
projectOwner:{projectid}, projectEditor:{projectid}, projectViewer:{projectid} for project roles
Federated identities using principal:// format (see GCP Principal identifiers documentation)

What properties can't be changed after creation?

The api, apiConfig, project, and role properties are all immutable and cannot be changed after the resource is created.

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides Azure Guides