---
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: "cURL"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/curl/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: 423
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "machine-only-decisions"
recommended_mcp_tools: []
estimated_tokens: 2259
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Create, rotate, and revoke secret keys for server-side Inttegro API access. This cURL representation preserves HTTP paths and JSON wire names.

### 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` is omitted from the response.

**Request — POST /keys/generate**

```bash
curl https://api.inttegro.com/keys/generate \
  --request POST \
  --header "Authorization: Bearer $INTTEGRO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"label":"Production checkout"}'
```

### Response

Returns the new `key`.

- `id` — `string` — required

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

- `issued_at` — `timestamp` — required

  Time the key was created, in ISO 8601 format.

- `label` — `string`

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

- `token` — `string` — required

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

- `token_type` — `string` — required

  Always `"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`:

```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` — `boolean` — required

  Whether the key can currently authenticate requests.

- `expires_at` — `timestamp`

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

- `id` — `string` — required

  Stable key identifier.

- `issued_at` — `timestamp` — required

  When the key was created.

- `label` — `string`

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

- `last_used_at` — `timestamp`

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

- `revoked_at` — `timestamp`

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

- `status` — `enum` — required

  Current lifecycle state:
  `"active"`,
  `"expired"`, or
  `"revoked"`.

- `token_type` — `string` — required

  Always `"bearer"`.

- `updated_at` — `timestamp`

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

- `usage_count` — `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`

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

- `number` — `integer`

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

- `size` — `integer`

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

### Response behavior

Returns `page` with `page.count`,
`page.has_more`,
`page.keys`, `page.number`,
`page.size`, and `page.total`. Each item
in `page.keys` 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

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

### Response behavior

Returns `{ "key": ... }` 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.

- `secret_key_id` — `string` — required

  Identifier of the key to update.

### Response behavior

Returns `{ "key": ... }` 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

  Identifier of the key to revoke.

### Response behavior

Returns `{ "key": ... }` with
`key.active` set to
`false`,
`key.status` set to
`"revoked"`, and
`key.revoked_at`; 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`

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

- `number` — `integer`

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

- `secret_key_id` — `string` — required

  Identifier of the key whose activity you want to review.

- `size` — `integer`

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

### Response behavior

Returns `key` with [public key
metadata](#public-key-metadata) and `usage` with exactly
`usage.count`, `usage.has_more`,
`usage.number`, `usage.rows`,
`usage.size`, and `usage.total`. Each row
contains exactly `usage.rows[].secret_key_id`,
`usage.rows[].occurred_at`, and
`usage.rows[].auth_result`; the key never includes
`token`.

## Related resources

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