---
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: "TypeScript"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/typescript/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: 433
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "machine-only-decisions"
recommended_mcp_tools: []
estimated_tokens: 2887
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Create, rotate, and revoke secret keys for server-side Inttegro API access. This TypeScript 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`

  Optional human-readable name for the key. Surrounding whitespace is
  removed. If the normalized value is empty, [`key.label`](https://typescript.inttegro.dev/v12.0.0) is omitted from the response.

**Request — POST /keys/generate**

```typescript
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.keys.generate({
  label: "Production checkout",
})
```

### Response

Returns the new `GeneratedSecretKey`.

- [`id`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

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

- [`issuedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp` — required

  Time the key was created, in ISO 8601 format.

- [`label`](https://typescript.inttegro.dev/v12.0.0) — `string`

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

- [`token`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

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

- [`tokenType`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

  Always [`Inttegro.SecretKeyTokenTypes.Bearer`](https://typescript.inttegro.dev/v12.0.0/variables/types_keys.SecretKeyTokenTypes.html#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://typescript.inttegro.dev/v12.0.0):

```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://typescript.inttegro.dev/v12.0.0) — `boolean` — required

  Whether the key can currently authenticate requests.

- [`expiresAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

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

- [`id`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

  Stable key identifier.

- [`issuedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp` — required

  When the key was created.

- [`label`](https://typescript.inttegro.dev/v12.0.0) — `string`

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

- [`lastUsedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

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

- [`revokedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

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

- [`status`](https://typescript.inttegro.dev/v12.0.0) — `enum` — required

  Current lifecycle state:
  [`Inttegro.SecretKeyStatuses.Active`](https://typescript.inttegro.dev/v12.0.0/variables/types_keys.SecretKeyStatuses.html#active),
  [`Inttegro.SecretKeyStatuses.Expired`](https://typescript.inttegro.dev/v12.0.0/variables/types_keys.SecretKeyStatuses.html#expired), or
  [`Inttegro.SecretKeyStatuses.Revoked`](https://typescript.inttegro.dev/v12.0.0/variables/types_keys.SecretKeyStatuses.html#revoked).

- [`tokenType`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

  Always [`Inttegro.SecretKeyTokenTypes.Bearer`](https://typescript.inttegro.dev/v12.0.0/variables/types_keys.SecretKeyTokenTypes.html#bearer).

- [`updatedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

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

- [`usageCount`](https://typescript.inttegro.dev/v12.0.0) — `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` — `number`

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

- `number` — `number`

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

- `size` — `number`

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

### Response behavior

Returns `SecretKeyPage` with [`page.count`](https://typescript.inttegro.dev/v12.0.0),
[`page.hasMore`](https://typescript.inttegro.dev/v12.0.0),
[`page.keys`](https://typescript.inttegro.dev/v12.0.0), [`page.number`](https://typescript.inttegro.dev/v12.0.0),
[`page.size`](https://typescript.inttegro.dev/v12.0.0), and [`page.total`](https://typescript.inttegro.dev/v12.0.0). Each item
in [`page.keys`](https://typescript.inttegro.dev/v12.0.0) 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

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

- `secretKeyId` — `string` — required

  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://typescript.inttegro.dev/v12.0.0) set to
`false`,
[`key.status`](https://typescript.inttegro.dev/v12.0.0) set to
[`Inttegro.SecretKeyStatuses.Revoked`](https://typescript.inttegro.dev/v12.0.0/variables/types_keys.SecretKeyStatuses.html#revoked), and
[`key.revokedAt`](https://typescript.inttegro.dev/v12.0.0); 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` — `number`

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

- `number` — `number`

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

- `secretKeyId` — `string` — required

  Identifier of the key whose activity you want to review.

- `size` — `number`

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

### Response behavior

Returns [`key`](https://typescript.inttegro.dev/v12.0.0) with [public key
metadata](#public-key-metadata) and [`usage`](https://typescript.inttegro.dev/v12.0.0) with exactly
[`usage.count`](https://typescript.inttegro.dev/v12.0.0), [`usage.hasMore`](https://typescript.inttegro.dev/v12.0.0),
[`usage.number`](https://typescript.inttegro.dev/v12.0.0), [`usage.rows`](https://typescript.inttegro.dev/v12.0.0),
[`usage.size`](https://typescript.inttegro.dev/v12.0.0), and [`usage.total`](https://typescript.inttegro.dev/v12.0.0). Each row
contains exactly [`usage.rows[].secretKeyId`](https://typescript.inttegro.dev/v12.0.0),
[`usage.rows[].occurredAt`](https://typescript.inttegro.dev/v12.0.0), and
[`usage.rows[].authResult`](https://typescript.inttegro.dev/v12.0.0); the key never includes
`token`.

## Related resources

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