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 (users, service accounts, groups) can access specific API configurations. This guide focuses on two capabilities: authoritative role binding for multiple members and non-authoritative member addition.

IAM bindings reference existing API Gateway API and ApiConfig resources. 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, meaning it replaces any existing member list for that role. The members array accepts various identity formats: individual users, service accounts, groups, or special identifiers like allUsers. The role property specifies which permissions to grant; here, roles/apigateway.viewer provides read-only access to the API config.

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 member to a role without replacing existing members. This non-authoritative approach lets you manage individual access grants independently, useful when different teams or stacks control different members of the same role. The member property accepts a single identity string rather than an array.

Beyond these examples

These snippets focus on specific IAM binding features: role-based access control and authoritative vs non-authoritative member management. 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)
Project-level configuration (project property)
Full policy replacement (ApiConfigIamPolicy resource)
Custom role definitions

These omissions are intentional: the goal is to illustrate how IAM bindings are 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 & Conflicts

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 a single member while preserving other members for that role.

Which IAM resources can I use together without conflicts?

gcp.apigateway.ApiConfigIamPolicy cannot be used with gcp.apigateway.ApiConfigIamBinding or gcp.apigateway.ApiConfigIamMember, as they will conflict. gcp.apigateway.ApiConfigIamBinding can be used with gcp.apigateway.ApiConfigIamMember only if they don’t grant privileges to the same role.

When should I use ApiConfigIamBinding vs ApiConfigIamMember?

Use gcp.apigateway.ApiConfigIamBinding when you want to manage all members for a specific role authoritatively. Use gcp.apigateway.ApiConfigIamMember when you want to add individual members without affecting other members for that role.

IAM Configuration

What format do custom roles need to follow?

Custom roles must use the format [projects|organizations]/{parent-name}/roles/{role-name}.

What member identity formats are supported?

Supported formats include allUsers, allAuthenticatedUsers, user:{email}, serviceAccount:{email}, group:{email}, domain:{domain}, projectOwner/Editor/Viewer:{projectid}, and federated identities like principal://iam.googleapis.com/....

Which properties are immutable after creation?

The api, apiConfig, project, role, and condition properties are all immutable and cannot be changed after resource creation.

Beta & Provider Requirements

Do I need a special provider for this resource?

Yes, this resource is in beta and requires the terraform-provider-google-beta provider.

Import & Migration

What import identifier formats are supported?

You can import using four formats: full path (projects/{project}/locations/global/apis/{api}/configs/{api_config}), project-scoped ({project}/{api}/{api_config}), api-scoped ({api}/{api_config}), or just {api_config}. Variables not provided in the import command are taken from the provider configuration.

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides Azure Guides