---
title: "API keys"
description: "Create, rotate, and revoke secret keys for server-side Inttegro API access."
canonical: "https://studio.inttegro.com/api/keys"
format: inttegro-machine-docs/v1
language: "C#"
sdk_version: "v10.3.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/csharp/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 431
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "machine-only-decisions"
recommended_mcp_tools: []
estimated_tokens: 3201
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Create, rotate, and revoke secret keys for server-side Inttegro API access. This C# representation uses the selected SDK's native names wherever Studio has a verified mapping.

### Five questions

#### Q1. Is API keys the right source for this task?

Use this reference for create, rotate, and revoke secret keys for server-side inttegro api access. Keep the four decision rules below with its exact operations and fields; do not infer a broader workflow from endpoint order.

#### Q2. What is the first decision rule for rotate a key without losing the only copy of its secret?

Generation is the only response that contains the complete bearer token.
Persist it directly to a server-side secrets manager and never depend on a
later lookup, page, update, revoke, or usage request to recover it.

#### Q3. What is the second decision rule for rotate a key without losing the only copy of its secret?

Rotation is an overlap procedure: generate a replacement, deploy it to the
intended integration, confirm usage on the replacement, then revoke the old
key. Updating a label does not rotate a token.

#### Q4. What is the third decision rule for rotate a key without losing the only copy of its secret?

Use a separate key per deployed integration so revocation has a bounded blast
radius. A revoked or expired key remains visible as audit metadata but cannot
authenticate requests.

#### Q5. What is the fourth decision rule for rotate a key without losing the only copy of its secret?

Never place a secret key in browser, mobile, repository, log, analytics, or
machine-generated diagnostic output. If exposed, replace and revoke it rather
than attempting to redact only the observed copy.

## Document content

# API keys

API keys authenticate your server to the Inttegro API. Create a separate key for each deployed integration so you can rotate or revoke one credential without interrupting the rest of your application.

## Rotate a key without losing the only copy of its secret

The four decision rules are in the machine preamble above.

## Generate a secret key

Creates a new secret key for your Inttegro account. Existing keys remain active.

The complete bearer token is returned **only in this response**. Lookup, list, update, revoke, and usage responses never return it. Save the token before your provisioning process finishes; Commerce cannot retrieve it for you later.

### Request body

The request body is optional. Omit it or send an empty JSON object for an
unlabeled key; include `label` to make the key easy to
identify during rotation. No other request properties are accepted.

- `label` — `string` — wire-only

  Optional human-readable name for the key. Surrounding whitespace is
  removed. If the normalized value is empty, [`Key.Label`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.GeneratedSecretKey.html) is omitted from the response.

**Request — POST /keys/generate**

```csharp
using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Keys.GenerateAsync(new {
  label = "Production checkout",
});
```

### Response

Returns the new `GeneratedSecretKey`.

- [`ID`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.GeneratedSecretKey.html) — `string` — required

  Stable identifier for managing the key. This is not the bearer credential.

- [`IssuedAt`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.GeneratedSecretKey.html) — `timestamp` — required

  Time the key was created, in ISO 8601 format.

- [`Label`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.GeneratedSecretKey.html) — `string`

  Normalized label. Omitted when no non-empty label was supplied.

- [`Token`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.GeneratedSecretKey.html) — `string` — required

  Complete bearer credential. Returned once and never returned by another
  key endpoint.

- [`TokenType`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.GeneratedSecretKey.html) — `string` — required

  Always [`Inttegro.SecretKeyTokenType.Bearer`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyTokenType.html#Inttegro_SecretKeyTokenType_Bearer).

```json
{
  "key": {
    "id": "sk_2xC7k9gK5yQnZ4w8P1sT6vR3",
    "issued_at": "2026-08-30T10:15:00Z",
    "label": "Production checkout",
    "token": "<returned-once-secret>",
    "token_type": "bearer"
  }
}
```

If `label` is omitted, empty, or contains only whitespace,
the successful response omits [`Key.Label`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.GeneratedSecretKey.html):

```json
{
  "key": {
    "id": "sk_2xC7k9gK5yQnZ4w8P1sT6vR3",
    "issued_at": "2026-08-30T10:15:00Z",
    "token": "<returned-once-secret>",
    "token_type": "bearer"
  }
}
```

## Public key metadata

Key-management responses other than generation never contain `token`. They contain only the following public metadata fields:

- [`Active`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKey.html) — `boolean` — required

  Whether the key can currently authenticate requests.

- [`ExpiresAt`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKey.html) — `timestamp`

  When the key expires. Omitted for a key without a fixed expiry.

- [`ID`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKey.html) — `string` — required

  Stable key identifier.

- [`IssuedAt`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKey.html) — `timestamp` — required

  When the key was created.

- [`Label`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKey.html) — `string`

  Human-readable label. Omitted when the key is unlabeled.

- [`LastUsedAt`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKey.html) — `timestamp`

  Most recent recorded use. Omitted when no usage timestamp is available.

- [`RevokedAt`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKey.html) — `timestamp`

  When the key was revoked. Omitted while the key has not been revoked.

- [`Status`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKey.html) — `enum` — required

  Current lifecycle state:
  [`Inttegro.SecretKeyStatus.Active`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyStatus.html#Inttegro_SecretKeyStatus_Active),
  [`Inttegro.SecretKeyStatus.Expired`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyStatus.html#Inttegro_SecretKeyStatus_Expired), or
  [`Inttegro.SecretKeyStatus.Revoked`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyStatus.html#Inttegro_SecretKeyStatus_Revoked).

- [`TokenType`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKey.html) — `string` — required

  Always [`Inttegro.SecretKeyTokenType.Bearer`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyTokenType.html#Inttegro_SecretKeyTokenType_Bearer).

- [`UpdatedAt`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKey.html) — `timestamp`

  When the label last changed. Omitted until the key is updated.

- [`UsageCount`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKey.html) — `integer`

  Number of recorded uses for the key. Omitted when the count is zero.

## List keys

Lists your keys, newest first. The response includes revoked and expired keys so you can audit previous rotations. It never includes bearer tokens.

### Request body

- `page` — `integer` — wire-only

  Page number. Defaults to `1`; `0` is
  normalized to `1`. Do not send with
  `number`.

- `number` — `integer` — wire-only

  Alias for `page`. Do not send both fields.

- `size` — `integer` — wire-only

  Number of keys per page. Defaults to `50`; values above
  `100` are capped at `100`.

### Response behavior

Returns `SecretKeyPage` with [`Page.Count`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyPage.html),
[`Page.HasMore`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyPage.html),
[`Page.Keys`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyPage.html), [`Page.Number`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyPage.html),
[`Page.Size`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyPage.html), and [`Page.Total`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyPage.html). Each item
in [`Page.Keys`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyPage.html) is [public key
metadata](#public-key-metadata) and omits `token`.

## Look up a key

Returns one of your keys. The response never includes the bearer token.

### Request body

- `secret_key_id` — `string` — required — wire-only

  Identifier returned when the key was generated. Send one key identifier.

### Response behavior

Returns `SecretKey` containing [public key
metadata](#public-key-metadata).

## Update a key label

Changes the label for one of your keys. It does not rotate the token or change whether the key is active.

### Request body

- `label` — `string` — required — wire-only

  New label. Surrounding whitespace is removed. Send an empty string to
  remove the label.

- `secret_key_id` — `string` — required — wire-only

  Identifier of the key to update.

### Response behavior

Returns `SecretKey` containing the updated [public key
metadata](#public-key-metadata) without `token`.

## Revoke a key

Permanently prevents a key from authenticating new requests. Revocation does not delete its metadata or usage history.

### Request body

- `secret_key_id` — `string` — required — wire-only

  Identifier of the key to revoke.

### Response behavior

Returns `SecretKey` with
[`Key.Active`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKey.html) set to
`false`,
[`Key.Status`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKey.html) set to
[`Inttegro.SecretKeyStatus.Revoked`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyStatus.html#Inttegro_SecretKeyStatus_Revoked), and
[`Key.RevokedAt`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKey.html); it never includes `token`
.

## Review key usage

Returns recorded authentication activity for one of your keys. Use it to confirm a replacement is active before revoking the previous credential.

### Request body

- `page` — `integer` — wire-only

  Page number. Defaults to `1`; `0` is
  normalized to `1`. Do not send with
  `number`.

- `number` — `integer` — wire-only

  Alias for `page`. Do not send both fields.

- `secret_key_id` — `string` — required — wire-only

  Identifier of the key whose activity you want to review.

- `size` — `integer` — wire-only

  Number of activity records per page. Defaults to `50`;
  values above `100` are capped at
  `100`.

### Response behavior

Returns [`Key`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyUsage.html) with [public key
metadata](#public-key-metadata) and [`Usage`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyUsage.html) with exactly
[`Usage.Count`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyUsage.html), [`Usage.HasMore`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyUsage.html),
[`Usage.Number`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyUsage.html), [`Usage.Rows`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyUsage.html),
[`Usage.Size`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyUsage.html), and [`Usage.Total`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyUsage.html). Each row
contains exactly [`Usage.Rows[].SecretKeyID`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyUsage.html),
[`Usage.Rows[].OccurredAt`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyUsage.html), and
[`Usage.Rows[].AuthResult`](https://dotnet.inttegro.dev/v10.3.0/api/Inttegro.SecretKeyUsage.html); the key never includes
`token`.

## Related resources

- [Create an application](https://studio.inttegro.com/machine/csharp/api/apps.md#create-an-app) — Receive the application's first secret key.