published on Friday, Sep 11, 2026 by incident-io
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
Rotateendpoint. - Managing keys at scale: use the
Show,List,Create,Update, andDeleteendpoints 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
viewerandincident_creatorcan assign those roles to a target key, but cannot assign theincident_editorrole, since it has additional scopes. - The same applies at the team level: A caller key with
schedules_editorat the account level can create a target key with that role for a specific team, but a key withschedules_editoronly for one team (Team A, say) cannot assign it at the account level or for another team, Team B. - The
api_keys_managerole 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
Deleteendpoint 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 dictionarydata "incident_get_api_key" "name" {
# arguments
}The following arguments are supported:
getApiKey Result
The following output properties are available:
- 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 stringAt - 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 List<string>Names - The team-level roles assigned to this API key
- Token
Last stringIssued At - 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 stringAt - 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 []string - The account-level roles assigned to this API key
- Team
Ids []string - IDs of teams that this API key is scoped to
- Team
Role []stringNames - The team-level roles assigned to this API key
- Token
Last stringIssued At - 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_ stringat - 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_ list(string)names - The team-level roles assigned to this API key
- token_
last_ stringissued_ at - 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 StringAt - 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 List<String>Names - The team-level roles assigned to this API key
- token
Last StringIssued At - 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 stringAt - 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 string[] - The account-level roles assigned to this API key
- team
Ids string[] - IDs of teams that this API key is scoped to
- team
Role string[]Names - The team-level roles assigned to this API key
- token
Last stringIssued At - 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_ strat - 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_ Sequence[str]names - The team-level roles assigned to this API key
- token_
last_ strissued_ at - 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 StringAt - 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 List<String>Names - The team-level roles assigned to this API key
- token
Last StringIssued At - 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
incidentTerraform Provider.
published on Friday, Sep 11, 2026 by incident-io