--- 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: "Go" sdk_version: "v11.0.1" reader_profile: optional reader_manifest: "https://studio.inttegro.com/machine/go/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: 431 model_token_report: "https://studio.inttegro.com/machine/token-report.json" preamble_questions: 5 preamble_source: "machine-only-decisions" recommended_mcp_tools: [] estimated_tokens: 3755 token_estimate_method: "utf8_bytes_divided_by_4" --- ## Machine preamble **Summary:** Create, rotate, and revoke secret keys for server-side Inttegro API access. This Go 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`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#GenerateParams.Label) to make the key easy to identify during rotation. No other request properties are accepted. - [`Label`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#GenerateParams.Label) — `string` Optional human-readable name for the key. Surrounding whitespace is removed. If the normalized value is empty, [`Key.Label`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Generated) is omitted from the response. **Request — POST /keys/generate** ```go package main import ( "context" "log" "os" inttegro "github.com/inttegro/inttegro-sdk-go/v11" "github.com/inttegro/inttegro-sdk-go/v11/secretkey" ) func main() { ctx := context.Background() client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY")) params := secretkey.GenerateParams{ Label: "Production checkout", } result, err := client.Keys.Generate(ctx, params) if err != nil { log.Fatal(err) } _ = result } ``` ### Response Returns the new `secretkey.Generated`. - [`ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Generated) — `string` — required Stable identifier for managing the key. This is not the bearer credential. - [`IssuedAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Generated) — `timestamp` — required Time the key was created, in ISO 8601 format. - [`Label`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Generated) — `string` Normalized label. Omitted when no non-empty label was supplied. - [`Token`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Generated) — `string` — required Complete bearer credential. Returned once and never returned by another key endpoint. - [`TokenType`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Generated) — `string` — required Always [`secretkey.TokenTypeBearer`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#TokenTypeBearer). ```json { "key": { "id": "sk_2xC7k9gK5yQnZ4w8P1sT6vR3", "issued_at": "2026-08-30T10:15:00Z", "label": "Production checkout", "token": "", "token_type": "bearer" } } ``` If [`Label`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#GenerateParams.Label) is omitted, empty, or contains only whitespace, the successful response omits [`Key.Label`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Generated): ```json { "key": { "id": "sk_2xC7k9gK5yQnZ4w8P1sT6vR3", "issued_at": "2026-08-30T10:15:00Z", "token": "", "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://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#SecretKey) — `boolean` — required Whether the key can currently authenticate requests. - [`ExpiresAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#SecretKey) — `timestamp` When the key expires. Omitted for a key without a fixed expiry. - [`ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#SecretKey) — `string` — required Stable key identifier. - [`IssuedAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#SecretKey) — `timestamp` — required When the key was created. - [`Label`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#SecretKey) — `string` Human-readable label. Omitted when the key is unlabeled. - [`LastUsedAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#SecretKey) — `timestamp` Most recent recorded use. Omitted when no usage timestamp is available. - [`RevokedAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#SecretKey) — `timestamp` When the key was revoked. Omitted while the key has not been revoked. - [`Status`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#SecretKey) — `enum` — required Current lifecycle state: [`secretkey.StatusActive`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#StatusActive), [`secretkey.StatusExpired`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#StatusExpired), or [`secretkey.StatusRevoked`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#StatusRevoked). - [`TokenType`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#SecretKey) — `string` — required Always [`secretkey.TokenTypeBearer`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#TokenTypeBearer). - [`UpdatedAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#SecretKey) — `timestamp` When the label last changed. Omitted until the key is updated. - [`UsageCount`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#SecretKey) — `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`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#PageParams.Page) — `int` Page number. Defaults to `1`; `0` is normalized to `1`. Do not send with [`Number`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#PageParams.Number). - [`Number`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#PageParams.Number) — `int` Alias for [`Page`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#PageParams.Page). Do not send both fields. - [`Size`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#PageParams.Size) — `int` Number of keys per page. Defaults to `50`; values above `100` are capped at `100`. ### Response behavior Returns `secretkey.Page` with [`Page.Count`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Page), [`Page.HasMore`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Page), [`Page.Keys`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Page), [`Page.Number`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Page), [`Page.Size`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Page), and [`Page.Total`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Page). Each item in [`Page.Keys`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Page) 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.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`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#UpdateParams.Label) — `string` — required New label. Surrounding whitespace is removed. Send an empty string to remove the label. - [`SecretKeyID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#UpdateParams.SecretKeyID) — `string` — required Identifier of the key to update. ### Response behavior Returns `secretkey.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.SecretKey` with [`Key.Active`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#SecretKey) set to `false`, [`Key.Status`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#SecretKey) set to [`secretkey.StatusRevoked`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#StatusRevoked), and [`Key.RevokedAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#SecretKey); 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`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#UsageParams.Page) — `int` Page number. Defaults to `1`; `0` is normalized to `1`. Do not send with [`Number`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#UsageParams.Number). - [`Number`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#UsageParams.Number) — `int` Alias for [`Page`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#UsageParams.Page). Do not send both fields. - [`SecretKeyID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#UsageParams.SecretKeyID) — `string` — required Identifier of the key whose activity you want to review. - [`Size`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#UsageParams.Size) — `int` Number of activity records per page. Defaults to `50`; values above `100` are capped at `100`. ### Response behavior Returns [`Key`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Usage) with [public key metadata](#public-key-metadata) and [`Usage`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Usage) with exactly [`Usage.Count`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Usage), [`Usage.HasMore`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Usage), [`Usage.Number`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Usage), [`Usage.Rows`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Usage), [`Usage.Size`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Usage), and [`Usage.Total`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Usage). Each row contains exactly [`Usage.Rows[].SecretKeyID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Usage), [`Usage.Rows[].OccurredAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Usage), and [`Usage.Rows[].AuthResult`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/secretkey#Usage); the key never includes `token`. ## Related resources - [Create an application](https://studio.inttegro.com/machine/go/api/apps.md#create-an-app) — Receive the application's first secret key.