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.
Operations
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.
Request
- cURL
- TypeScript
- Go
- Python
- PHP
- Ruby
- Java
- C#
curl https://api.inttegro.com/keys/generate \
--request POST \
--header "Authorization: Bearer $INTTEGRO_API_KEY" \
--header "Content-Type: application/json" \
--data '{"label":"Production checkout"}'
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",
})
package main
import (
"context"
"log"
"os"
inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)
func main() {
ctx := context.Background()
client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))
params := inttegro.GenerateSecretKeyParams{
Label: "Production checkout",
}
result, err := client.Keys.Generate(ctx, params)
if err != nil {
log.Fatal(err)
}
_ = result
}
import os
import inttegro
client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.keys.generate(inttegro.keys.GenerateRequest(
label="Production checkout",
))
<?php
use Inttegro\Client;
$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->keys->generate([
'label' => 'Production checkout',
]);
require "inttegro"
client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.keys.generate(
label: "Production checkout"
)
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);
}
}
using Inttegro;
using var inttegro = new InttegroClient(
Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Keys.GenerateAsync(new {
label = "Production checkout",
});
Response
A successful request returns HTTP 200 with exactly one top-level property, key.
200 response
If label is omitted, empty, or contains only whitespace, the successful response omits label:
200 response for an unlabeled key
Status codes
| Status | Meaning |
|---|---|
200 | A new active key was created. Save key.token immediately. |
401 | The bearer key is missing, invalid, expired, or revoked. |
422 | The JSON body is invalid, contains unsupported attributes, or key generation failed. |
Non-200 responses use the standard Commerce API error format.
Public key metadata
Key-management responses other than generation never contain token. They contain only the following public metadata fields:
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
Response behavior
HTTP 200 returns page with exactly count, has_more, keys, number, size, and total. Each item in keys is public key metadata and omits token. Invalid pagination returns 422; missing or invalid authentication returns 401.
Look up a key
Returns one of your keys. The response never includes the bearer token.
Request body
Response behavior
HTTP 200 returns { "key": ... } containing public key metadata. An unknown key ID returns 404; an invalid request returns 422; missing or invalid authentication returns 401.
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
Response behavior
HTTP 200 returns { "key": ... } containing the updated public key metadata without token. A missing key returns 404; an invalid request or failed update returns 422; an operation already in progress returns 409; temporary service unavailability returns 503; and missing or invalid authentication returns 401.
Revoke a key
Permanently prevents a key from authenticating new requests. Revocation does not delete its metadata or usage history.
Request body
Response behavior
HTTP 200 returns { "key": ... } with active: false, status: "revoked", and revoked_at; it never includes token. A missing key returns 404; an invalid request or failed revocation returns 422; an operation already in progress returns 409; temporary service unavailability returns 503; and missing or invalid authentication returns 401.
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
Response behavior
HTTP 200 returns key with public key metadata and usage with exactly count, has_more, number, rows, size, and total. Each row contains exactly secret_key_id, occurred_at, and auth_result; the key never includes token. A missing key returns 404; an invalid request or failed lookup returns 422; missing or invalid authentication returns 401.
Related resources
- Create an application — Receive the application's first secret key.