1. Registry
  2. Packages
  3. Incident Provider
  4. API Docs
  5. getApiKey
Viewing docs for incident 7.0.0
published on Friday, Sep 11, 2026 by incident-io
Viewing docs for incident 7.0.0
published on Friday, Sep 11, 2026 by incident-io

    Manage API keys for your organization.

    This API lets you view, create, update, delete, and rotate API keys programmatically, including configuring account-level roles and roles scoped to specific teams.

    Common use cases include:

    • API key rotation: You can issue a new access token for any API key using the Rotate endpoint.
    • Managing keys at scale: use the Show, List, Create, Update, and Delete endpoints to automate API key lifecycle management.

    Permissions model

    To use these endpoints, your API key must have the api_keys_manage role granted at either the account level or for specific teams.

    In addition, the following rules apply, when a “caller” API key is managing a “target” API key:

    • A caller key can only assign roles whose scopes are a subset of its own scopes. For example, a key with viewer and incident_creator can assign those roles to a target key, but cannot assign the incident_editor role, since it has additional scopes.
    • The same applies at the team level: A caller key with schedules_editor at the account level can create a target key with that role for a specific team, but a key with schedules_editor only for one team (Team A, say) cannot assign it at the account level or for another team, Team B.
    • The api_keys_manage role cannot be assigned via the API. To create a key with that role, you must go to Settings → API keys in the dashboard, and click “Add new”, creating a key with the “View, create, edit, delete or rotate API keys” role (api_keys_manage).
    • The Delete endpoint does not check whether the calling API key holds the scopes of the key being deleted. However, a team-scoped key can only delete keys belonging to its teams.
    • To rotate the token of an API key, use the Rotate endpoint or by clicking “Rotate token” on any API key listed in the dashboard. The same permissions limitations apply as when creating or updating an API key.

    Finding role names and team IDs

    To find valid values for role_names, team_ids, and team_role_names, go to Settings → API keys in the dashboard. Click to either edit an existing key or create a new one, select the desired roles and teams, and then use the copy button to get hold of the role and team identifiers as JSON.

    Use this data source to look up an existing API key, either by id or by name. This is how you read the roles held by a key somebody created in the dashboard without managing it as an incident.ApiKey resource. Set exactly one of the two lookup attributes; setting both, or neither, is rejected at plan time.

    A key’s token is returned only when incident.io issues one, so there is no token attribute here: a lookup can tell you what a key may do and when it was last used, but never how to authenticate as it.

    Example Usage

    import * as pulumi from "@pulumi/pulumi";
    import * as incident from "@pulumi/incident";
    
    // Look up an existing API key by name, such as one created in the dashboard.
    const ci = incident.getApiKey({
        name: "CI deploy key",
    });
    // Or by ID, to reference a key another module manages. Names aren't unique, so an ID is
    // the way through an ambiguous lookup.
    const reporting = incident.getApiKey({
        id: "01G0J1EXE7AXZ2C93K61WBPYEH",
    });
    export const ciKeyRoles = ci.then(ci => ci.roleNames);
    export const ciKeyLastUsedAt = ci.then(ci => ci.lastUsedAt);
    
    import pulumi
    import pulumi_incident as incident
    
    # Look up an existing API key by name, such as one created in the dashboard.
    ci = incident.get_api_key(name="CI deploy key")
    # Or by ID, to reference a key another module manages. Names aren't unique, so an ID is
    # the way through an ambiguous lookup.
    reporting = incident.get_api_key(id="01G0J1EXE7AXZ2C93K61WBPYEH")
    pulumi.export("ciKeyRoles", ci.role_names)
    pulumi.export("ciKeyLastUsedAt", ci.last_used_at)
    
    package main
    
    import (
    	"github.com/pulumi/pulumi-terraform-provider/sdks/go/incident/v7/incident"
    	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
    )
    
    func main() {
    	pulumi.Run(func(ctx *pulumi.Context) error {
    		// Look up an existing API key by name, such as one created in the dashboard.
    		ci, err := incident.LookupApiKey(ctx, &incident.LookupApiKeyArgs{
    			Name: pulumi.StringRef("CI deploy key"),
    		}, nil)
    		if err != nil {
    			return err
    		}
    		// Or by ID, to reference a key another module manages. Names aren't unique, so an ID is
    		// the way through an ambiguous lookup.
    		_, err = incident.LookupApiKey(ctx, &incident.LookupApiKeyArgs{
    			Id: pulumi.StringRef("01G0J1EXE7AXZ2C93K61WBPYEH"),
    		}, nil)
    		if err != nil {
    			return err
    		}
    		ctx.Export("ciKeyRoles", ci.RoleNames)
    		ctx.Export("ciKeyLastUsedAt", ci.LastUsedAt)
    		return nil
    	})
    }
    
    using System.Collections.Generic;
    using System.Linq;
    using Pulumi;
    using Incident = Pulumi.Incident;
    
    return await Deployment.RunAsync(() => 
    {
        // Look up an existing API key by name, such as one created in the dashboard.
        var ci = Incident.GetApiKey.Invoke(new()
        {
            Name = "CI deploy key",
        });
    
        // Or by ID, to reference a key another module manages. Names aren't unique, so an ID is
        // the way through an ambiguous lookup.
        var reporting = Incident.GetApiKey.Invoke(new()
        {
            Id = "01G0J1EXE7AXZ2C93K61WBPYEH",
        });
    
        return new Dictionary<string, object?>
        {
            ["ciKeyRoles"] = ci.Apply(getApiKeyResult => getApiKeyResult.RoleNames),
            ["ciKeyLastUsedAt"] = ci.Apply(getApiKeyResult => getApiKeyResult.LastUsedAt),
        };
    });
    
    package generated_program;
    
    import com.pulumi.Context;
    import com.pulumi.Pulumi;
    import com.pulumi.core.Output;
    import com.pulumi.incident.IncidentFunctions;
    import com.pulumi.incident.inputs.GetApiKeyArgs;
    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) {
            // Look up an existing API key by name, such as one created in the dashboard.
            final var ci = IncidentFunctions.getApiKey(GetApiKeyArgs.builder()
                .name("CI deploy key")
                .build());
    
            // Or by ID, to reference a key another module manages. Names aren't unique, so an ID is
            // the way through an ambiguous lookup.
            final var reporting = IncidentFunctions.getApiKey(GetApiKeyArgs.builder()
                .id("01G0J1EXE7AXZ2C93K61WBPYEH")
                .build());
    
            ctx.export("ciKeyRoles", ci.roleNames());
            ctx.export("ciKeyLastUsedAt", ci.lastUsedAt());
        }
    }
    
    variables:
      # Look up an existing API key by name, such as one created in the dashboard.
      ci:
        fn::invoke:
          function: incident:getApiKey
          arguments:
            name: CI deploy key
      # Or by ID, to reference a key another module manages. Names aren't unique, so an ID is
      # the way through an ambiguous lookup.
      reporting:
        fn::invoke:
          function: incident:getApiKey
          arguments:
            id: 01G0J1EXE7AXZ2C93K61WBPYEH
    outputs:
      # A lookup can tell you what a key may do, but never how to authenticate as it: the token
      # is returned only when incident.io issues one, so there's no token attribute here.
      ciKeyRoles: ${ci.roleNames}
      # last_used_at is null for a key nothing has authenticated with, which is how you find the
      # ones worth deleting.
      ciKeyLastUsedAt: ${ci.lastUsedAt}
    
    Example coming soon!
    

    Using getApiKey

    Two invocation forms are available. The direct form accepts plain arguments and either blocks until the result value is available, or returns a Promise-wrapped result. The output form accepts Input-wrapped arguments and returns an Output-wrapped result.

    function getApiKey(args: GetApiKeyArgs, opts?: InvokeOptions): Promise<GetApiKeyResult>
    function getApiKeyOutput(args: GetApiKeyOutputArgs, opts?: InvokeOutputOptions): Output<GetApiKeyResult>
    def get_api_key(id: Optional[str] = None,
                    name: Optional[str] = None,
                    opts: Optional[InvokeOptions] = None) -> GetApiKeyResult
    def get_api_key_output(id: pulumi.Input[Optional[str]] = None,
                    name: pulumi.Input[Optional[str]] = None,
                    opts: Optional[InvokeOutputOptions] = None) -> Output[GetApiKeyResult]
    func LookupApiKey(ctx *Context, args *LookupApiKeyArgs, opts ...InvokeOption) (*LookupApiKeyResult, error)
    func LookupApiKeyOutput(ctx *Context, args *LookupApiKeyOutputArgs, opts ...InvokeOption) LookupApiKeyResultOutput

    > Note: This function is named LookupApiKey in the Go SDK.

    public static class GetApiKey 
    {
        public static Task<GetApiKeyResult> InvokeAsync(GetApiKeyArgs args, InvokeOptions? opts = null)
        public static Output<GetApiKeyResult> Invoke(GetApiKeyInvokeArgs args, InvokeOptions? opts = null)
        public static Output<GetApiKeyResult> Invoke(GetApiKeyInvokeArgs args, InvokeOutputOptions opts)
    }
    public static CompletableFuture<GetApiKeyResult> getApiKey(GetApiKeyArgs args, InvokeOptions options)
    public static Output<GetApiKeyResult> getApiKey(GetApiKeyArgs args, InvokeOptions options)
    public static Output<GetApiKeyResult> getApiKey(GetApiKeyArgs args, InvokeOutputOptions options)
    
    fn::invoke:
      function: incident:index/getApiKey:getApiKey
      arguments:
        # arguments dictionary
    data "incident_get_api_key" "name" {
        # arguments
    }

    The following arguments are supported:

    Id string
    Unique identifier for this API key
    Name string
    The name of the API key, for the user's reference
    Id string
    Unique identifier for this API key
    Name string
    The name of the API key, for the user's reference
    id string
    Unique identifier for this API key
    name string
    The name of the API key, for the user's reference
    id String
    Unique identifier for this API key
    name String
    The name of the API key, for the user's reference
    id string
    Unique identifier for this API key
    name string
    The name of the API key, for the user's reference
    id str
    Unique identifier for this API key
    name str
    The name of the API key, for the user's reference
    id String
    Unique identifier for this API key
    name String
    The name of the API key, for the user's reference

    getApiKey Result

    The following output properties are available:

    Comments string
    Freeform notes about this API key
    CreatedAt string
    When the API key was created
    Id string
    Unique identifier for this API key
    LastUsedAt string
    When the key was last used to authenticate a request
    Name string
    The name of the API key, for the user's reference
    RoleNames List<string>
    The account-level roles assigned to this API key
    TeamIds List<string>
    IDs of teams that this API key is scoped to
    TeamRoleNames List<string>
    The team-level roles assigned to this API key
    TokenLastIssuedAt string
    When the current token for this API was last issued. This is the last time the token was rotated, or when it was initially created. Older tokens may remain valid for up to an hour after they have been rotated, configured when you call the rotate endpoint.
    Comments string
    Freeform notes about this API key
    CreatedAt string
    When the API key was created
    Id string
    Unique identifier for this API key
    LastUsedAt string
    When the key was last used to authenticate a request
    Name string
    The name of the API key, for the user's reference
    RoleNames []string
    The account-level roles assigned to this API key
    TeamIds []string
    IDs of teams that this API key is scoped to
    TeamRoleNames []string
    The team-level roles assigned to this API key
    TokenLastIssuedAt string
    When the current token for this API was last issued. This is the last time the token was rotated, or when it was initially created. Older tokens may remain valid for up to an hour after they have been rotated, configured when you call the rotate endpoint.
    comments string
    Freeform notes about this API key
    created_at string
    When the API key was created
    id string
    Unique identifier for this API key
    last_used_at string
    When the key was last used to authenticate a request
    name string
    The name of the API key, for the user's reference
    role_names list(string)
    The account-level roles assigned to this API key
    team_ids list(string)
    IDs of teams that this API key is scoped to
    team_role_names list(string)
    The team-level roles assigned to this API key
    token_last_issued_at string
    When the current token for this API was last issued. This is the last time the token was rotated, or when it was initially created. Older tokens may remain valid for up to an hour after they have been rotated, configured when you call the rotate endpoint.
    comments String
    Freeform notes about this API key
    createdAt String
    When the API key was created
    id String
    Unique identifier for this API key
    lastUsedAt String
    When the key was last used to authenticate a request
    name String
    The name of the API key, for the user's reference
    roleNames List<String>
    The account-level roles assigned to this API key
    teamIds List<String>
    IDs of teams that this API key is scoped to
    teamRoleNames List<String>
    The team-level roles assigned to this API key
    tokenLastIssuedAt String
    When the current token for this API was last issued. This is the last time the token was rotated, or when it was initially created. Older tokens may remain valid for up to an hour after they have been rotated, configured when you call the rotate endpoint.
    comments string
    Freeform notes about this API key
    createdAt string
    When the API key was created
    id string
    Unique identifier for this API key
    lastUsedAt string
    When the key was last used to authenticate a request
    name string
    The name of the API key, for the user's reference
    roleNames string[]
    The account-level roles assigned to this API key
    teamIds string[]
    IDs of teams that this API key is scoped to
    teamRoleNames string[]
    The team-level roles assigned to this API key
    tokenLastIssuedAt string
    When the current token for this API was last issued. This is the last time the token was rotated, or when it was initially created. Older tokens may remain valid for up to an hour after they have been rotated, configured when you call the rotate endpoint.
    comments str
    Freeform notes about this API key
    created_at str
    When the API key was created
    id str
    Unique identifier for this API key
    last_used_at str
    When the key was last used to authenticate a request
    name str
    The name of the API key, for the user's reference
    role_names Sequence[str]
    The account-level roles assigned to this API key
    team_ids Sequence[str]
    IDs of teams that this API key is scoped to
    team_role_names Sequence[str]
    The team-level roles assigned to this API key
    token_last_issued_at str
    When the current token for this API was last issued. This is the last time the token was rotated, or when it was initially created. Older tokens may remain valid for up to an hour after they have been rotated, configured when you call the rotate endpoint.
    comments String
    Freeform notes about this API key
    createdAt String
    When the API key was created
    id String
    Unique identifier for this API key
    lastUsedAt String
    When the key was last used to authenticate a request
    name String
    The name of the API key, for the user's reference
    roleNames List<String>
    The account-level roles assigned to this API key
    teamIds List<String>
    IDs of teams that this API key is scoped to
    teamRoleNames List<String>
    The team-level roles assigned to this API key
    tokenLastIssuedAt String
    When the current token for this API was last issued. This is the last time the token was rotated, or when it was initially created. Older tokens may remain valid for up to an hour after they have been rotated, configured when you call the rotate endpoint.

    Package Details

    Repository
    incident incident-io/terraform-provider-incident
    License
    Notes
    This Pulumi package is based on the incident Terraform Provider.
    Viewing docs for incident 7.0.0
    published on Friday, Sep 11, 2026 by incident-io

      Try Pulumi Cloud free.
      Your team will thank you.

      Start free trial