Invite-only closed beta / Stripe test mode

ソフトウェアのライセンス販売とアクティベーションを、まず1本のAPIから。

Activatist は、開発者が自分のソフトウェアのライセンスキーを販売し、購入後にアプリ内で検証・有効化できるようにするAPIです。このページはプログラム初学者でも実装できるように、用語、流れ、主要言語のコード例を日本語でまとめています。

SDKで実装する認証の概念を見る API Referenceを見る

POST /v1/licenses/activate
Content-Type: application/json

{
  "product_id": "prod_123",
  "license_key": "LIC1-XXXX-XXXX-XXXX-XXXX",
  "device_fingerprint": "device-abc"
}

現在の前提: 招待制 closed beta です。Stripe は test mode、live 決済と一般公開は別レビューが必要です。ギフトカード、ポイント、第三者キー転売、C2C resale には使えません。

Closed Beta Status

今できること / まだできないこと

今できること

招待制sellerのtest-mode販売
license validate / activate / deactivate の実装検証
購入完了ページでのlicense確認
承認済みファイルのauthorized download検証

まだできないこと

live Stripe決済
public seller self-serve
public launch
自動スキャン前提の大規模ファイル販売

Start Here

あなたがやりたいことは？

アプリにライセンス認証を組み込む SDK、activate、validate、deactivate から始めます。 Activatistで商品を販売する seller申請、Product作成、Stripe Connect、file deliveryの流れを見ます。 API仕様を確認する OpenAPIからendpoint、request、response schemaを確認します。

Concepts

まず押さえる4つの言葉

Product

販売するソフトウェア本体です。例: デスクトップアプリ、プラグイン、開発ツール。1つの Product に価格、説明、サポート先、アクティベーション上限が紐づきます。

License Key

購入後に発行されるキーです。ユーザーがアプリに入力し、アプリが Activatist API に送って検証します。ログに出してはいけません。

Activation

「この端末で使い始める」操作です。同じ端末の再アクティベーションは冪等で、別端末は activation_limit を超えると拒否されます。

Device Fingerprint

端末を見分けるためのアプリ側IDです。メールアドレスや氏名などの個人情報を入れず、安定したランダムIDを使います。

Before You Start

実装者が用意するもの

API base URLhttps://license.souko.work

product_idclosed beta中は、運営/adminが作成・承認したProduct IDをsellerへ共有します。public launch後は管理画面で確認できる想定です。

SDK package使う言語のSDKをダウンロードし、アプリに同梱します。

ライセンス入力UIユーザーが購入後に受け取ったキーを入力する画面を用意します。

API keyは不要です

ライセンス認証APIには、seller/admin用のBearer tokenは不要です。 アプリは product_id とユーザー入力のlicense keyをSDKへ渡します。

認証の境界

runtime license API は seller/admin bearer token なしで呼びます。ユーザーのアプリに組み込むAPIです。

seller/admin API は verified Firebase bearer token が必要です。これらのtokenをブラウザ配布アプリに埋め込んではいけません。

CORSの考え方

このドキュメントの対象は macOS / Windows / Linux のデスクトップアプリです。Webブラウザだけでの実装は、端末IDの永続性とseat管理が不安定になりやすいため対象外です。

Quickstart

最短の実装手順

SDKをダウンロードする下のSDKセクションから使う言語のzipを取得します。
product_idを設定する商品ごとのIDをアプリ設定に入れます。これは公開アプリ内に入っていて問題ありません。
activateを呼ぶユーザーが入力したライセンスキーをSDKへ渡します。SDKが端末IDを生成・保存してruntime APIを呼びます。
起動時はvalidateを呼ぶ毎回activateせず、起動時や24時間に1回程度の状態確認はvalidateを使います。
409だけ明確に表示するactivation limit exceeded は「利用可能な端末数の上限」として案内します。

Lifecycle

validate / activate / deactivate の使い分け

タイミング	呼ぶAPI	理由
初回ライセンス入力	`activate`	この端末を利用枠として登録します。
アプリ起動時	`validate`	seatを増やさず、revoke/refund/expiredを確認します。
24時間に1回程度	`validate`	状態変化を反映しつつ、過剰なAPI呼び出しを避けます。
ユーザーが端末解除	`deactivate`	ポリシーが許す場合に利用枠を空けます。
ネットワーク不通	短いgrace	最後の成功状態を短時間だけ使い、復旧後にvalidateします。

Device Fingerprint

端末IDはSDKが生成・保存する

端末IDはアプリ実装者が考えるより、SDK側でOS別の安全な保存先に作るのが扱いやすいです。UUID v4相当のランダムIDなら衝突確率は実用上ほぼ無視できます。メール、氏名、電話番号、IPアドレス、raw hardware serial は使いません。

backendは端末IDのraw値を保存せず、HMAC hashとして扱います。アプリ側でもログには出さないでください。

macOS

Application Support 配下、可能なら Keychain。ファイル保存なら権限を絞ります。

Windows

AppData 配下、可能なら Credential Manager / DPAPI を検討します。

Linux

XDG config 配下に保存し、権限は `0600` 相当にします。

Activation Deep Dive

アクティベーションを重点的に理解する

アクティベーションは「ライセンスキーが正しいか」だけでなく、「この端末を利用枠として登録できるか」も確認します。

購入者、アプリ、Activatist Runtime API、ライセンス状態の認証概念図

成功するケース

ライセンスが active
Product が一致している
同じ端末で再実行した
別端末でも activation_limit 内

失敗するケース

キーが存在しない、または別Product用
refund / dispute / revoked / suspended / expired
別端末が上限を超えた
device_fingerprint が空、または不安定

Runtime Endpoints

アプリに組み込む3つのAPI

POST/v1/licenses/validate

起動時や定期チェックで使います。activation_count は増えません。

POST/v1/licenses/activate

初回認証や端末登録で使います。activation_limit を超えた別端末は `409 conflict` になります。

POST/v1/licenses/deactivate

端末の解除で使います。ポリシー上許可されている場合、利用枠を空けます。

SDK

主要言語のアクティベーション実装例

通常はこちらを使ってください。SDKは端末IDの生成・保存、runtime API呼び出し、エラー処理をまとめるためのものです。

closed beta note: 現在はソース配布です。npm / PyPI / RubyGems / Packagist / crates.io / Maven Central / NuGet などへの公開は、API shape 承認後のリリース作業として扱います。

JavaScript / TypeScript

import { ActivatistClient } from "@activatist/client";

const client = new ActivatistClient({ productId: "prod_123" });
const result = await client.activate(licenseKey);

Python

from activatist import ActivatistClient

client = ActivatistClient(product_id="prod_123")
result = client.activate(license_key)

Go

client, _ := activatist.NewClient("prod_123")
result, err := client.Activate(ctx, licenseKey)

All SDKs全言語まとめてダウンロード JavaScript / TypeScriptfetch client + type definitions Pythonurllib client + unittest Gonet/http + context RubyNet::HTTP + Minitest PHPstream_context + typed exception Rustreqwest + serde JavaJDK standard http client C#HttpClient + System.Text.Json SwiftURLSession + Swift Testing C++transport injection client KotlinJVM java.net.http client

Code Samples

SDKを使わない場合のHTTP実装例

SDKを使えない環境向けです。通常のデスクトップアプリでは上のSDK例を優先してください。

JavaScript

ブラウザやElectronで使いやすい fetch の例です。

Appendix

エラー時の考え方

HTTP	意味	アプリ側の表示例
400	入力が不足、形式が不正	入力内容を確認してください。
403	キーが使えない状態	このライセンスは利用できません。
404	対象が見つからない	ライセンス情報が見つかりません。
409	アクティベーション上限超過	利用可能な端末数の上限に達しました。
429	短時間にリクエストが多すぎる	少し待ってから再試行してください。
5xx	一時的なサーバー障害	時間をおいて再試行してください。

レスポンス例

{
  "valid": true,
  "status": "active",
  "activation_limit": 1,
  "activation_count": 1,
  "features": ["pro"]
}

エラーbody例

{
  "request_id": "req_example",
  "code": "activation_limit_exceeded",
  "message": "Activation limit reached"
}

request_id はサポート問い合わせやログ照合に使います。license key と一緒にログへ出さないでください。

Seller Flow

商品販売・ファイル配布まで行う場合

アプリに認証を組み込むだけならruntime APIの3つで十分です。Activatist上で商品を売る場合は、seller申請、Stripe Connect、Product review、file upload/finalize、admin approval、test checkout、buyer completion/download の順に進みます。

Seller Quickstartを見る

API Map

API一覧

スキーマやrequest/responseの詳細は Interactive API Reference で確認できます。

購入・利用者向け

GET /v1/public/products/{slug}
POST /v1/public/products/{slug}/checkout
POST /v1/purchases/complete
POST /v1/purchases/files/{file_id}/download-intent
POST /v1/licenses/validate
POST /v1/licenses/activate
POST /v1/licenses/deactivate

販売者向け

POST /v1/sellers
POST /v1/sellers/stripe/account-link
POST /v1/products
POST /v1/products/{product_id}/submit-review
POST /v1/products/{product_id}/files/upload-intent
POST /v1/products/{product_id}/files/{file_id}/finalize

管理・運用向け

GET /v1/admin/sellers
PATCH /v1/admin/products/{product_id}/review
GET /v1/admin/product-files
PATCH /v1/admin/products/{product_id}/files/{file_id}/review
POST /v1/stripe/webhook
GET /readyz

Safety Rules

実装時にやってはいけないこと

ログに出さない

ライセンスキー、completion token、buyer email、Firebase token、Bearer token、Stripe/Resend/R2/Cloudflare の秘密情報、presigned URL はログや共有メモに出さないでください。

端末IDに個人情報を使わない

device_fingerprint にメールアドレス、氏名、電話番号、住所などを入れないでください。ランダムIDを作って端末内に保存する方式が扱いやすいです。

毎回 activate しない

起動時チェックは validate、端末登録は activate、端末解除は deactivate と役割を分けると、ユーザー体験とサーバー負荷が安定します。

対象外の商品に使わない

Activatist は first-party software license 用です。ギフトカード、ポイント、第三者キー転売、C2C resale には使えません。

最後に確認すること

product_id を設定した Runtime APIにはBearer tokenを付けていない license keyをログに出していない起動時はvalidate、初回登録はactivateに分けた 409は端末数上限として表示する request_idを問い合わせ用に扱える