---
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: "Java"
sdk_version: "v8.3.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/java/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: 3274
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Create, rotate, and revoke secret keys for server-side Inttegro API access. This Java 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://java.inttegro.dev/v8.3.0/com/inttegro/keys/GeneratedSecretKey.html) is omitted from the response.

**Request — POST /keys/generate**

```java
import com.inttegro.Client;
import com.inttegro.keys.GenerateSecretKeyParams;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = GenerateSecretKeyParams.builder()
      .label("Production checkout")
      .build();
    var result = client.keys().generate(params);
  }
}
```

### Response

Returns the new `GeneratedSecretKey`.

- [`id(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/GeneratedSecretKey.html) — `string` — required

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

- [`issuedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/GeneratedSecretKey.html) — `timestamp` — required

  Time the key was created, in ISO 8601 format.

- [`label(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/GeneratedSecretKey.html) — `string`

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

- [`token(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/GeneratedSecretKey.html) — `string` — required

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

- [`tokenType(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/GeneratedSecretKey.html) — `string` — required

  Always [`SecretKeyTokenType.BEARER`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyTokenType.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://java.inttegro.dev/v8.3.0/com/inttegro/keys/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://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKey.html) — `boolean` — required

  Whether the key can currently authenticate requests.

- [`expiresAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKey.html) — `timestamp`

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

- [`id(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKey.html) — `string` — required

  Stable key identifier.

- [`issuedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKey.html) — `timestamp` — required

  When the key was created.

- [`label(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKey.html) — `string`

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

- [`lastUsedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKey.html) — `timestamp`

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

- [`revokedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKey.html) — `timestamp`

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

- [`status(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKey.html) — `enum` — required

  Current lifecycle state:
  [`SecretKeyStatus.ACTIVE`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyStatus.html#ACTIVE),
  [`SecretKeyStatus.EXPIRED`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyStatus.html#EXPIRED), or
  [`SecretKeyStatus.REVOKED`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyStatus.html#REVOKED).

- [`tokenType(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKey.html) — `string` — required

  Always [`SecretKeyTokenType.BEARER`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyTokenType.html#BEARER).

- [`updatedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKey.html) — `timestamp`

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

- [`usageCount(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/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`

  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 `SecretKeyPage` with [`page(…).count(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyPage.html),
[`page(…).hasMore(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyPage.html),
[`page(…).keys(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyPage.html), [`page(…).number(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyPage.html),
[`page(…).size(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyPage.html), and [`page(…).total(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyPage.html). Each item
in [`page(…).keys(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/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

  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

- `secretKeyId(…)` — `String` — required

  Identifier of the key to revoke.

### Response behavior

Returns `SecretKey` with
[`key(…).active(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKey.html) set to
`false`,
[`key(…).status(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKey.html) set to
[`SecretKeyStatus.REVOKED`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyStatus.html#REVOKED), and
[`key(…).revokedAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/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`

  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.

- `secretKeyId(…)` — `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(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyUsage.html) with [public key
metadata](#public-key-metadata) and [`usage(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyUsage.html) with exactly
[`usage(…).count(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyUsage.html), [`usage(…).hasMore(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyUsage.html),
[`usage(…).number(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyUsage.html), [`usage(…).rows(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyUsage.html),
[`usage(…).size(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyUsage.html), and [`usage(…).total(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyUsage.html). Each row
contains exactly [`usage(…).rows(…)[].secretKeyId(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyUsage.html),
[`usage(…).rows(…)[].occurredAt(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyUsage.html), and
[`usage(…).rows(…)[].authResult(…)`](https://java.inttegro.dev/v8.3.0/com/inttegro/keys/SecretKeyUsage.html); the key never includes
`token`.

## Related resources

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