External integration (Management API)

Integration overview

There are two directions: your systems operate Usakey, and Usakey reports changes back to your systems. Use API keys for the first direction and webhooks for the second.

Your systems → Usakey

Using API keys

An API key is the credential your systems use to call Usakey. Create keys in the API keys screen and grant each integration only the smallest set of required operations.

Managing the customer portal's OIDC connections (sign-in settings) requires sso:read / sso:write. They used to be covered by customers:read / customers:write, but the permission that can replace an identity provider is now separate from customer records. Existing API keys that manage OIDC connections get SCOPE_REQUIRED (HTTP 403) until they have the new permissions. API-key permissions cannot be changed after creation, so create a new key with sso:read / sso:write, switch your integration to it, and revoke the old key.

Choose the right integration

Your systems → Usakey

Managing licenses

Issue, update, suspend, resume, and revoke licenses through APIs under /mgmt/v1/. These endpoints are called the Management API. The example below issues a license after billing confirms payment.

Send an Idempotency-Key header with creation requests (POST). It is required when you issue a license, convert a trial, or create a customer, product, policy, reseller, customer organization, organization group, group membership, license user, OIDC connection, or license assignment; without it, the request is rejected with IDEMPOTENCY_KEY_REQUIRED. It is optional when you create a webhook endpoint, and sending one there prevents duplicates in the same way. It is not required for updates (PATCH) or deletes (DELETE).

POST /mgmt/v1/licenses
Authorization: Bearer usk_live_…
Idempotency-Key: 7e2c4d5a-6f44-4b8f-90f4-4ee9b34d66e2
Content-Type: application/json

{
  "product_id": "prod_01K123EXAMPLE",
  "policy_id": "pol_01K123EXAMPLE",
  "customer_id": "cus_01K123EXAMPLE",
  "expires_at": "2027-08-24T00:00:00Z",
  "entitlements": { "export_pdf": true }
}

This operation requires the licenses:write scope.

The setting that lets the product app start a trial with email verification (the trial policy it uses and the 24-hour limit) can be read and changed with GET / PATCH /mgmt/v1/products/{product_id}/trial-signup (products:read / products:write) as well as on the product's edit page in the Console. The checks are the same as in the Console, and choosing a policy needs a plan that includes trials.

Sealed files for a product (files shipped with the product that only devices with a valid license can open) can be read and turned on with GET / POST /mgmt/v1/products/{product_id}/sealed-files (products:read / products:write) as well as on the product's page in the Console. POST takes no body and gives the same result however many times it is sent (it does not use Idempotency-Key). Once on, sealed files cannot be turned off. The Team plan or higher is required; otherwise the response is PLAN_ENTITLEMENT_REQUIRED. The response carries current_key right away; if the sealing key can't be reached for a moment, the response is 503 SEALED_FILES_KEY_UNAVAILABLE, so send it again later. current_key.sealing_key is the one-line public key for the sealing tool and is not a secret. The files themselves are never sent to Usakey. Sealing does not stop an administrator of a licensed device from extracting the data after the app opens it, and it does not prove who made a file, so have the app check a hash of files that must not be swapped.

The API reference contains customers, policies, activations, audit events, and all field definitions.

Your systems → Usakey

Operate from an AI assistant (MCP)

AI assistants such as Claude Code and Codex can operate this page’s APIs through conversation. MCP (Model Context Protocol) is a common way for an AI assistant to call external services. Usakey provides https://usakey.jp/mcp; add it to your assistant and sign in in a browser, then ask for tasks such as “suspend this license.” The same connection can read skills for integrating a product app.

Setup flow

1. Add the MCP server https://usakey.jp/mcp to your AI assistant by giving it instructions or running the command below.
2. Sign in to Usakey in a browser and choose the workspace and permitted scopes in the confirmation screen. For management operations, start with test and the smallest necessary scope. To allow “Allow day-to-day operations” or more in production or both, the person granting it must have two-factor authentication set up.
3. Ask the AI assistant in English or Japanese. The assistant maintains and refreshes the login state.

# Claude Code (after adding, choose usakey in /mcp and Authenticate)
claude mcp add --transport http --scope user usakey https://usakey.jp/mcp

# Codex (the browser login starts after adding it)
codex mcp add usakey --url https://usakey.jp/mcp

The Product app integration (Runtime API) quickstart explains the prompt and confirmation choices. Revoke the connection at any time from AI assistant connections in Console.

Permissions and API scopes

Only workspace owners and admins can grant management operations. Usakey creates a connection-specific API key with the chosen scopes and environment, but never displays the key value. The connection stops working if the person who granted it leaves the workspace or loses permission to grant management access. The initial choice on the consent screen is “Allow read-only access” when Usakey could verify the app's publisher and your role can grant management access; otherwise it is “Use skills only”.

Environments and “both”

When granting management access, choose the environment on the consent screen.

• Test (test-environment products only)
• Production (changes licenses for distributed products)
• Both (test and production products)

A connection with both environments holds one API key per environment with the same permissions, so “API keys” in Console lists two keys for the connection. Two-factor authentication is required under the same conditions as production. Each time the assistant calls a tool, Usakey picks the key in this order.

1. The tool argument environment (test or live). It appears only on connections with both and is not sent to the API.
2. The environment of the target named by an ID (license, then activation, policy, and product). When environment and the target's environment differ, Usakey stops without calling the API and returns ENVIRONMENT_REQUIRED with a hint.
3. Lists without an ID (list_products, list_policies, list_licenses, list_runtime_events) called without environment run on both environments, merge the results, and tag each item with environment. That uses two monthly calls. The next page comes from a cursor that keeps the position in each environment.
4. Creating a product (create_product) requires environment. Product names and codes are unique across test and live, so give the test and live copies different names and codes.
5. The usage report (get_usage_report) needs environment or product_id. Test and live numbers are not added together.
6. What is not kept per environment (customers, user-level licensing, sign-in settings, webhooks, audit logs, the plan, and your own Stripe integration) uses the production key.

The operation history in Console shows which environment's key the actor used (for example, “MCP: Codex / … (Production key)”). You can change the environment, permissions, and tool sets later with “Edit settings” in AI assistant connections (Console asks you to confirm your identity within the last 10 minutes before saving). Widening test to both keeps the current key; keys for a removed environment or for changed permissions are recreated and the old ones are revoked.

In the usage report (get_usage_report), active_machines is the number of devices activated in the period and not deactivated. It includes devices of suspended and expired licenses, so it is not the number of devices that can use the product right now.

Options your plan does not include are dimmed on the consent screen with one of these reasons.

• This workspace's plan can't create production products, so Production and Both aren't available (Personal plan or higher).
• This workspace's plan doesn't include user-level licenses (Personal plan or higher).
• This workspace's plan doesn't include customer organizations or resellers (Team plan or higher).
• This workspace's plan doesn't include OIDC sign-in for the customer portal (Team plan or higher).

Use it safely

• Do not auto-approve mutation tools. In particular, revoke_license cannot be undone. Each tool is marked as read, create, or change for the assistant.
• Operations that cannot be undone run only when the target is confirmed: the last four characters of the key (confirm_key_last4) to revoke a license, and the name (confirm_name) to retire a policy (retire_policy) or archive a customer (archive_customer). Before approving, check that the assistant got the value from you.
• Customer names, notes, and metadata may contain instructions aimed at the AI. A person must approve changes, and permissions should be minimal.
• When the AI runs the bundled SDK-download script, review the command in the assistant’s confirmation screen before approving it.

Supported protocol details

• MCP 2026-07-28 (Streamable HTTP, stateless requests with _meta, MCP-Protocol-Version, Mcp-Method, and Mcp-Name headers, plus server/discover) and the 2025-03-26 through 2025-11-25 initialize flow
• The io.modelcontextprotocol/skills extension (skills/list, skills/get, resources/directory/read) and skill:// resources
• OAuth 2.1 authorization code with required PKCE S256, refresh-token rotation, Protected Resource Metadata (RFC 9728), authorization-server metadata (RFC 8414), Client ID Metadata Document, dynamic client registration (RFC 7591), resource (RFC 8707), and iss (RFC 9207)

Local server with an API key (optional)

The official SDK also includes a local MCP server at usakey-sdk/mcp/. It uses an API key instead of browser login, making it suitable for CI and other environments without a browser. Only this local server can issue offline activation files and save license keys to a file without exposing them in the conversation. It does not provide skills; install skills through the MCP above or the ZIP.

Setup flow

1. Install Node.js 20.3 or later. No additional package is required.
2. Download the official SDK, verify its checksum, and extract it. The server is under usakey-sdk/mcp/.
3. Create a dedicated API key in Console under “Development & integrations” → “API keys”. Start with test and the smallest necessary scopes. Store the key in a file readable only by you.
4. Check the connection, then register it with your AI assistant.

The following Linux/macOS example extracts into the home directory. At the read line, paste the API key and press Enter; it is not kept on screen or in shell history. On Windows, verify the checksum with PowerShell Get-FileHash -Algorithm SHA256.

cd ~
curl -fSLO https://usakey.jp/downloads/usakey-sdk.zip
curl -fSLO https://usakey.jp/downloads/usakey-sdk.zip.sha256
sha256sum -c usakey-sdk.zip.sha256    # on macOS, use shasum -a 256 -c
unzip -q usakey-sdk.zip

mkdir -p ~/.usakey && chmod 700 ~/.usakey
read -rs USAKEY_KEY
(umask 077 && printf '%s\n' "$USAKEY_KEY" > ~/.usakey/api-key)
unset USAKEY_KEY

USAKEY_API_URL=https://usakey.jp \
USAKEY_MANAGEMENT_API_KEY_FILE=$HOME/.usakey/api-key \
node ~/usakey-sdk/mcp/bin/usakey-mcp.mjs --check

The local server prints its messages in Japanese for now. The check exits with status 0 when the API key is valid, and with status 1 when the connection fails. This check makes one Management API call.

claude mcp add usakey --scope user \
  -e USAKEY_API_URL=https://usakey.jp \
  -e USAKEY_MANAGEMENT_API_KEY_FILE=$HOME/.usakey/api-key \
  -- node $HOME/usakey-sdk/mcp/bin/usakey-mcp.mjs

{
  "mcpServers": {
    "usakey": {
      "command": "node",
      "args": ["/Users/<user-name>/usakey-sdk/mcp/bin/usakey-mcp.mjs"],
      "env": {
        "USAKEY_API_URL": "https://usakey.jp",
        "USAKEY_MANAGEMENT_API_KEY_FILE": "/Users/<user-name>/.usakey/api-key"
      }
    }
  }
}

codex mcp add usakey \
  --env USAKEY_API_URL=https://usakey.jp \
  --env USAKEY_MANAGEMENT_API_KEY_FILE=$HOME/.usakey/api-key \
  -- node $HOME/usakey-sdk/mcp/bin/usakey-mcp.mjs

Choose API-key scopes

Use the local server safely

• Do not auto-approve mutation tools. In particular, revoke_license cannot be undone.
• Data from Usakey, including customer names, notes, and metadata, may contain instructions aimed at the AI. A person must approve changes and the API key must be minimal.
• The local server reads files only when you provide an offline activation request (.usakeyreq); it rejects other file formats before sending them.

The full tool list, configuration, and troubleshooting steps are in usakey-sdk/mcp/README.md.

Usakey → your systems

Webhooks

Usakey can automatically report license issuance, expiry, suspension, resumption, revocation, and new device activations to your systems. Your CRM, customer notifications, and renewal workflows can start from those events, so polling Usakey is usually unnecessary (see the monthly allowance below).

Besides your own systems (signed JSON), you can send notifications to Slack, Microsoft Teams, Google Chat, or Chatwork. Chat notifications are not signed, so use a notification to your own system to start business processes.

Configure and receive webhooks

1. In Console, open “Development & integrations” → “Webhooks” and register a public HTTPS URL and the events to send. Changing or deleting an endpoint later, or switching its signing secret, asks you to confirm your identity within the last 10 minutes.
2. Store the signing secret, shown only once, in a secure area of your server.
3. Verify the signature against the body and headers exactly as received, before parsing the JSON.
4. Record X-Usakey-Event-Id to prevent duplicate work and return HTTP 2xx right away. Run follow-up work, such as CRM updates, asynchronously after returning 2xx.

Usakey treats a delivery that does not receive 2xx within 30 seconds as failed and retries it. If you finish heavy processing before responding, the same event can arrive again and again.

The same event can arrive more than once. Connection errors and HTTP 408, 425, 429, or 5xx responses are retried for up to 24 hours. Other 4xx responses are treated as non-retryable.

Each webhook delivery attempt uses your plan's monthly allowance. Every attempt counts once, including each retry. “Send test event” and “Resend” in Console also count once each. The monthly allowance is Evaluation 100, Personal 2,000, Team 20,000, and Enterprise 200,000 (it resets on the 1st of each month, Japan time). After the allowance is used up, later events that month are neither delivered nor retried; Usakey only records in the Console “Audit log” that the limit was reached. Retries during an outage on your side can use up the allowance quickly, so for important workflows also reconcile with a Management API list call about once a day. Additional webhook deliveries are not currently sold as an add-on, so a larger allowance requires a higher plan.

Verifying webhook signatures

Webhooks to your own systems include these headers (chat notifications have no signature headers).

HMAC-SHA256 creates a verification value from the shared secret known only to Usakey and the receiver. The signed value is timestamp.event_id.raw_body, and the result is v1=<lowercase hex>. raw_body means the received body exactly as received, including whitespace, line breaks, and key order. Verify it before parsing and rebuilding JSON. Use the signing-secret string exactly as displayed (its UTF-8 bytes) as the HMAC key; do not decode it as Base64URL.

Reject events whose X-Usakey-Timestamp differs from the current time by more than five minutes (a recommendation; Usakey does not set a receiver-side tolerance). During a signing-secret rotation, deliveries switch to the new secret at the switch time. Around that time, accept signatures made with either the old or the new secret.

Verification examples

Ruby

require "openssl"

# raw_body: the body exactly as received, before parsing the JSON
# secrets: signing-secret strings (both old and new during a rotation)
def valid_usakey_signature?(raw_body, headers, secrets, now: Time.now.to_i)
  timestamp = headers.fetch("X-Usakey-Timestamp")
  event_id = headers.fetch("X-Usakey-Event-Id")
  signature = headers.fetch("X-Usakey-Signature")
  return false if (now - Integer(timestamp, 10)).abs > 300 # reject events more than five minutes off

  signed = "#{timestamp}.#{event_id}.".b + raw_body.b
  secrets.any? do |secret|
    expected = "v1=" + OpenSSL::HMAC.hexdigest("SHA256", secret, signed)
    OpenSSL.secure_compare(expected, signature)
  end
end

Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the body exactly as received (Buffer); verify before JSON.parse
// secrets: signing-secret strings (both old and new during a rotation)
export function isValidUsakeySignature(rawBody, headers, secrets, now = Math.floor(Date.now() / 1000)) {
  const timestamp = headers["x-usakey-timestamp"] ?? "";
  const eventId = headers["x-usakey-event-id"] ?? "";
  const signature = Buffer.from(headers["x-usakey-signature"] ?? "");
  if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > 300) return false; // reject events more than five minutes off

  const signed = Buffer.concat([Buffer.from(`${timestamp}.${eventId}.`), rawBody]);
  return secrets.some((secret) => {
    const expected = Buffer.from(`v1=${createHmac("sha256", secret).update(signed).digest("hex")}`);
    return expected.length === signature.length && timingSafeEqual(expected, signature);
  });
}

Webhook events and payloads

Use the human-readable event label in your UI. The JSON type and ID field names remain fixed English identifiers for receiving programs.

{
  "id": "evt_01K789EXAMPLE",
  "type": "activation.created",
  "api_version": "2026-08-24",
  "created_at": "2026-08-25T10:30:00.000+09:00",
  "tenant_id": "ten_01K000EXAMPLE",
  "data": {
    "activation_id": "act_01KABCEXAMPLE",
    "license_id": "lic_01K456EXAMPLE",
    "product_id": "prod_01K123EXAMPLE"
  }
}

api_version is the webhook payload version and is versioned separately from the API.

Choose * (Send all events) to receive every event type, including types added later.A risk rule that stops a device sends activation.risk_blocked; one that suspends the license sends license.suspended.

customer_id is null when the license was issued without a customer. Ignore unknown fields so future additions remain compatible.