Skip to main content
View as Markdown

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.

POST/keys/generate

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.

TypeScript SDK requestGenerateSecretKeyRequestv12.0.0
  • Name
    label
    Type
    string
    Description

    Optional human-readable name for the key. Surrounding whitespace is removed. If the normalized value is empty,

    label

    is omitted from the response.

Request

POST/keys/generate
SDK versionv12.0.0
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.

TypeScript SDK responseGeneratedSecretKeyv12.0.0
  • Name
    id
    Type
    string
    Required
    required
    Description

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

  • Name
    issuedAt
    Type
    Date
    Required
    required
    Description

    Time the key was created, in ISO 8601 format.

  • Name
    label
    Type
    string
    Description

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

  • Name
    token
    Type
    string
    Required
    required
    Description

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

  • Name
    tokenType
    Type
    SecretKeyTokenType
    Required
    required
    Description

    Always Inttegro.SecretKeyTokenTypes.Bearer.

Response

SDK versionv12.0.0
KeyResponse {
  key: { … },
}

If label is omitted, empty, or contains only whitespace, the successful response omits

label

:

Response for an unlabeled key

SDK versionv12.0.0
KeyResponse {
  key: { … },
}

Public key metadata

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

TypeScript SDK responseSecretKeyv12.0.0
POST/keys/page

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​

TypeScript SDK requestPageSecretKeysRequestv12.0.0
  • Name
    page
    Type
    number
    Description

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

  • Name
    number
    Type
    number
    Description

    Alias for page. Do not send both fields.

  • Name
    size
    Type
    number
    Description

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

Response behavior​

Returns SecretKeyPage with count, hasMore, keys, number, size, and total. Each item in keys is public key metadata and omits token.

POST/keys/lookup

Look up a key

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

Request body​

TypeScript SDK requestLookupSecretKeyRequestv12.0.0
  • Name
    secretKeyId
    Type
    string
    Required
    required
    Description

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

Response behavior​

Returns SecretKey containing public key metadata.

POST/keys/update

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​

TypeScript SDK requestUpdateSecretKeyRequestv12.0.0
  • Name
    label
    Type
    string
    Required
    required
    Description

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

  • Name
    secretKeyId
    Type
    string
    Required
    required
    Description

    Identifier of the key to update.

Response behavior​

Returns SecretKey containing the updated public key metadata without token.

POST/keys/destroy

Revoke a key

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

Request body​

TypeScript SDK requestDestroySecretKeyRequestv12.0.0
  • Name
    secretKeyId
    Type
    string
    Required
    required
    Description

    Identifier of the key to revoke.

Response behavior​

Returns SecretKey with active set to false, status set to Inttegro.SecretKeyStatuses.Revoked, and revokedAt; it never includes token .

POST/keys/usage

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​

TypeScript SDK requestSecretKeyUsageRequestv12.0.0
  • Name
    page
    Type
    number
    Description

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

  • Name
    number
    Type
    number
    Description

    Alias for page. Do not send both fields.

  • Name
    secretKeyId
    Type
    string
    Required
    required
    Description

    Identifier of the key whose activity you want to review.

  • Name
    size
    Type
    number
    Description

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

Response behavior​

Returns key with public key metadata and usage with exactly count, hasMore, number, rows, size, and total. Each row contains exactly rows[].secretKeyId, rows[].occurredAt, and rows[].authResult; the key never includes token.