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

## Machine preamble

**Summary:** Create, rotate, and revoke secret keys for server-side Inttegro API access. This PHP 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://php.inttegro.dev/v12.0.0/classes/Inttegro-GeneratedSecretKey.html) is omitted from the response.

**Request — POST /keys/generate**

```php
<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->keys->generate([
  'label' => 'Production checkout',
]);
```

### Response

Returns the new `GeneratedSecretKey`.

- [`id`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-GeneratedSecretKey.html) — `string` — required

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

- [`issued_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-GeneratedSecretKey.html) — `timestamp` — required

  Time the key was created, in ISO 8601 format.

- [`label`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-GeneratedSecretKey.html) — `string`

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

- [`token`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-GeneratedSecretKey.html) — `string` — required

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

- [`token_type`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-GeneratedSecretKey.html) — `string` — required

  Always [`\Inttegro\SecretKey\TokenType::Bearer`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey-TokenType.html#enumcase_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://php.inttegro.dev/v12.0.0/classes/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://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey.html) — `boolean` — required

  Whether the key can currently authenticate requests.

- [`expires_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey.html) — `timestamp`

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

- [`id`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey.html) — `string` — required

  Stable key identifier.

- [`issued_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey.html) — `timestamp` — required

  When the key was created.

- [`label`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey.html) — `string`

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

- [`last_used_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey.html) — `timestamp`

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

- [`revoked_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey.html) — `timestamp`

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

- [`status`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey.html) — `enum` — required

  Current lifecycle state:
  [`\Inttegro\SecretKey\Status::Active`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey-Status.html#enumcase_Active),
  [`\Inttegro\SecretKey\Status::Expired`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey-Status.html#enumcase_Expired), or
  [`\Inttegro\SecretKey\Status::Revoked`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey-Status.html#enumcase_Revoked).

- [`token_type`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey.html) — `string` — required

  Always [`\Inttegro\SecretKey\TokenType::Bearer`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey-TokenType.html#enumcase_Bearer).

- [`updated_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey.html) — `timestamp`

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

- [`usage_count`](https://php.inttegro.dev/v12.0.0/classes/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://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyPage.html),
[`page.has_more`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyPage.html),
[`page.keys`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyPage.html), [`page.number`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyPage.html),
[`page.size`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyPage.html), and [`page.total`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyPage.html). Each item
in [`page.keys`](https://php.inttegro.dev/v12.0.0/classes/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://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey.html) set to
`false`,
[`key.status`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey.html) set to
[`\Inttegro\SecretKey\Status::Revoked`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKey-Status.html#enumcase_Revoked), and
[`key.revoked_at`](https://php.inttegro.dev/v12.0.0/classes/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://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyUsage.html) with [public key
metadata](#public-key-metadata) and [`usage`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyUsage.html) with exactly
[`usage.count`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyUsage.html), [`usage.has_more`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyUsage.html),
[`usage.number`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyUsage.html), [`usage.rows`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyUsage.html),
[`usage.size`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyUsage.html), and [`usage.total`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyUsage.html). Each row
contains exactly [`usage.rows[].secret_key_id`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyUsage.html),
[`usage.rows[].occurred_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyUsage.html), and
[`usage.rows[].auth_result`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-SecretKeyUsage.html); the key never includes
`token`.

## Related resources

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