バージョン: 最新版

認証

OmiseはAPIキーでHTTP Basic認証を使用します。リクエストを安全に認証し、各操作に適したキーを選択する方法を学びましょう。

概要

すべてのOmise APIリクエストは、APIキーのいずれかを使用して認証する必要があります。Omiseは目的に応じて異なるキータイプを提供しており、それぞれ特定のアクセス権限とセキュリティ要件があります。

クイックスタート

公開鍵 (pkey_*) → クライアントサイドコード、トークン/ソースの作成のみ
秘密鍵 (skey_*) → サーバーサイドコード、完全なAPIアクセス
絶対にクライアントサイドコードや公開リポジトリで秘密鍵を公開しないでください

APIキー

キータイプ

Omiseは3種類のAPIキーを提供しています。

キータイプ	フォーマット	用途	使用場所	アクセスレベル
公開鍵	`pkey_test_` / `pkey_live_`	カードのトークン化、ソースの作成	クライアントサイド（ブラウザ、モバイルアプリ）	制限付き - トークンとソースの作成のみ可能
秘密鍵	`skey_test_` / `skey_live_`	Charge、顧客、返金、すべての操作	サーバーサイドのみ	完全なAPIアクセス
Chain Key	`chain_*`	サブマーチャントに対する親アカウント操作	サーバーサイドのみ	サブマーチャント管理

テストキー vs 本番キー

各キータイプにはテストバージョンと本番バージョンがあります。

テストキー（開発用）

キー文字列に _test_ を含む
例: skey_test_5xuy4w91xqz7d1w9u0t
✅ 開発とテストに安全
✅ テストカード番号を受け入れる
✅ 実際のお金を処理しない
✅ テストWebhookをトリガー

本番キー（プロダクション）

_test_ を含まない
例: skey_live_5xuy4w91xqz7d1w9u0t
⚠️ 実際の支払いを処理
⚠️ 実際のカードに課金
⚠️ 安全に保管する必要がある

セキュリティクリティカル

**本番キーをバージョン管理にコミットしないでください。**環境変数とセキュアなシークレット管理システムを使用してください。

APIキーの検索

Omise Dashboardにログイン
設定 → キーに移動
開発用のテストキーをコピー
本番環境の準備ができたら本番キーをコピー

このページから新しいキーを生成したり、侵害されたキーを無効化できます。

認証の仕組み

OmiseはHTTP Basic認証を使用します。

ユーザー名: APIキー
パスワード: 空白のまま（空文字列）

APIキーはAuthorizationヘッダーにBase64エンコードされた文字列として送信されます。

Authorization: Basic <base64(api_key:)>

コロンに注意

パスワードが空であっても、エンコード時にAPIキーの後にコロン(:)を付ける必要があります。

認証の例

cURLの使用

# 秘密鍵を使用
curl https://api.omise.co/account \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

# 公開鍵を使用
curl https://vault.omise.co/tokens \
  -X POST \
  -u pkey_test_5xuy4w91xqz7d1w9u0t: \
  -d "card[name]=John Doe" \
  -d "card[number]=4242424242424242" \
  -d "card[expiration_month]=12" \
  -d "card[expiration_year]=2025" \
  -d "card[security_code]=123"

Rubyの使用

require 'omise'

# 秘密鍵を設定
Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

# 認証されたリクエストを作成
account = Omise::Account.retrieve

# トークン用の公開鍵を使用
Omise.vault_api_key = 'pkey_test_5xuy4w91xqz7d1w9u0t'
token = Omise::Token.create({
  card: {
    name: 'John Doe',
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2025,
    security_code: '123'
  }
})

Pythonの使用

import omise

# 秘密鍵を設定
omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

# 認証されたリクエストを作成
account = omise.Account.retrieve()

# トークン用の公開鍵を使用
omise.api_public = 'pkey_test_5xuy4w91xqz7d1w9u0t'
token = omise.Token.create(
    name='John Doe',
    number='4242424242424242',
    expiration_month=12,
    expiration_year=2025,
    security_code='123'
)

PHPの使用

<?php
require_once 'vendor/autoload.php';

// 秘密鍵を設定
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');
define('OMISE_PUBLIC_KEY', 'pkey_test_5xuy4w91xqz7d1w9u0t');

// 認証されたリクエストを作成
$account = OmiseAccount::retrieve();

// トークン用の公開鍵を使用
$token = OmiseToken::create(array(
    'card' => array(
        'name' => 'John Doe',
        'number' => '4242424242424242',
        'expiration_month' => 12,
        'expiration_year' => 2025,
        'security_code' => '123'
    )
));

Node.jsの使用

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t',
  publicKey: 'pkey_test_5xuy4w91xqz7d1w9u0t'
});

// 認証されたリクエストを作成
const account = await omise.account.retrieve();

// トークン用の公開鍵を使用
const token = await omise.tokens.create({
  card: {
    name: 'John Doe',
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2025,
    security_code: '123'
  }
});

Goの使用

package main

import (
    "github.com/omise/omise-go"
    "github.com/omise/omise-go/operations"
)

func main() {
    client, _ := omise.NewClient(
        "pkey_test_5xuy4w91xqz7d1w9u0t",
        "skey_test_5xuy4w91xqz7d1w9u0t",
    )

    // 認証されたリクエストを作成
    account, _ := client.Account()

    // トークン用の公開鍵を使用
    token, _ := client.CreateToken(&operations.CreateToken{
        Name:            "John Doe",
        Number:          "4242424242424242",
        ExpirationMonth: 12,
        ExpirationYear:  2025,
        SecurityCode:    "123",
    })
}

使用するキー

公開鍵を使用する場合:

✅ クライアントサイド操作（ブラウザ、モバイルアプリ）

カードデータからトークンを作成
代替決済方法用のソースを作成
機密性の高いカード情報を扱うすべての操作

理由: 公開鍵はトークンとソースの作成のみが可能で、カードに課金したり機密性の高いアカウントデータにアクセスしたりできないため、クライアントサイドコードに埋め込んでも安全です。

// ✅ 安全 - クライアントサイドJavaScriptの公開鍵
Omise.setPublicKey('pkey_test_5xuy4w91xqz7d1w9u0t');
Omise.createToken('card', cardData, function(status, response) {
  // トークンをサーバーに送信
});

秘密鍵を使用する場合:

✅ サーバーサイド操作のみ

Chargeの作成
顧客の管理
返金の処理
送金の作成
アカウント情報へのアクセス
お金や機密データを含むすべての操作

理由: 秘密鍵は完全なAPIアクセス権を持っており、絶対に公開してはいけません。

# ✅ 安全 - サーバーのみの秘密鍵
Omise.api_key = ENV['OMISE_SECRET_KEY']
charge = Omise::Charge.create({
  amount: 100000,
  currency: 'thb',
  card: params[:omise_token]
})

❌ 絶対にしないこと:

<!-- ❌ 危険 - HTMLで秘密鍵が公開されている -->
<script>
  const secretKey = 'skey_live_5xuy4w91xqz7d1w9u0t';
</script>

// ❌ 危険 - クライアントサイドコードの秘密鍵
fetch('https://api.omise.co/charges', {
  headers: {
    'Authorization': 'Basic ' + btoa('skey_live_...:')
  }
});

セキュリティベストプラクティス

1. キーを安全に保管

✅ 良い例: 環境変数

# .envファイル（gitにコミットしないこと）
OMISE_PUBLIC_KEY=pkey_test_5xuy4w91xqz7d1w9u0t
OMISE_SECRET_KEY=skey_test_5xuy4w91xqz7d1w9u0t

# コード内でアクセス
Omise.api_key = ENV['OMISE_SECRET_KEY']

✅ 良い例: シークレット管理システム

AWS Secrets Manager
Google Cloud Secret Manager
Azure Key Vault
HashiCorp Vault

❌ 悪い例: ハードコードされたキー

# ❌ キーをハードコードしないこと
Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

2. テストと本番を分離

# 開発環境
OMISE_SECRET_KEY=skey_test_...

# 本番環境
OMISE_SECRET_KEY=skey_live_...

3. キーを定期的にローテーション

キーが侵害された疑いがある場合:

Dashboardで新しいキーを生成
新しいキーでアプリケーションを更新
十分にテスト
古いキーを無効化

4. キーの権限を制限

Omiseはまだ詳細なキー権限をサポートしていませんが、最小権限の原則に従ってください:

可能な限り公開鍵を使用
秘密鍵は安全なサーバーのみに保管
チームメンバー間でキーを共有しない（各自が独自のダッシュボードアカウントを持つべき）

5. キーの使用を監視

Dashboardログを定期的に確認
異常な活動のアラートを設定
失敗した認証試行を監視

認証エラー

401 認証されていません

原因: 無効または欠落したAPIキー

{
  "object": "error",
  "code": "authentication_failure",
  "message": "authentication failed"
}

解決策:

✅ APIキーが正しいことを確認
✅ キーが無効化されていないことを確認
✅ 操作に適したキーを使用していることを確認
✅ キーに余分なスペースや文字がないか確認

403 Forbidden

原因: キーは有効だがこの操作の権限がない

{
  "object": "error",
  "code": "forbidden",
  "message": "key has insufficient permissions"
}

解決策:

✅ 公開鍵の代わりに秘密鍵を使用
✅ アカウントがこの機能へのアクセス権を持っているか確認
✅ キーが制限されていないことを確認

APIバージョニング

Omise-Versionヘッダーを使用してリクエストでAPIバージョンを指定します。

curl https://api.omise.co/charges \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -H "Omise-Version: 2019-05-29"

指定しない場合、リクエストはアカウントのデフォルトAPIバージョン（Dashboardで設定）を使用します。

APIバージョニングの詳細 →

認証のテスト

アカウントエンドポイントでテスト

認証をテストする最も簡単な方法:

# 秘密鍵のテスト
curl https://api.omise.co/account \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

# 公開鍵のテスト（失敗するはず - 公開鍵は /account にアクセスできない）
curl https://api.omise.co/account \
  -u pkey_test_5xuy4w91xqz7d1w9u0t:

期待されるレスポンス（秘密鍵）:

{
  "object": "account",
  "id": "acct_5xuy4w91xqz7d1w9u0t",
  "email": "merchant@example.com",
  "created_at": "2025-01-01T00:00:00Z",
  ...
}

期待されるレスポンス（公開鍵）:

{
  "object": "error",
  "code": "authentication_failure",
  "message": "authentication failed"
}

よくある質問

複数のアプリケーションで同じキーを使用できますか？

はい、しかし本番環境では推奨されません。技術的には可能ですが、異なるアプリケーションに別々のキーを使用することで以下のメリットがあります:

セキュリティ（他に影響を与えずに1つのキーを無効化）
監視（アプリケーションごとの使用状況を追跡）
デバッグ（どのアプリに問題があるか特定）

完全に分離されたアプリケーションにはサブマーチャントアカウントの使用を検討してください。

秘密鍵が侵害されたらどうなりますか？

Dashboardですぐに新しい秘密鍵を生成
新しいキーでアプリケーションを更新
侵害されたキーを無効化
不正なChargeがないかアカウントを監視
疑わしい活動が見られた場合は support@omise.co に連絡

ダウンタイムなしでキーを再生成できますか？

はい！ Omiseでは複数のアクティブなキーを同時に持つことができます:

新しいキーを生成
新しいキーでアプリケーションをデプロイ
新しいキーが機能することを確認
古いキーを無効化

これによりダウンタイムゼロでキーをローテーションできます。

APIキーは期限切れになりますか？

いいえ、Omise APIキーは自動的に期限切れになりません。ただし、以下を行うべきです:

キーを定期的にローテーション（6〜12か月ごと）
未使用のキーを無効化
チームメンバーの退職後に新しいキーを生成

APIキーの権限を制限できますか？

現在、Omiseには2つの権限レベルがあります:

公開鍵 - トークン/ソース作成に制限
秘密鍵 - 完全なAPIアクセス

詳細な権限制御はまだ利用できません。分離にはサブマーチャントアカウントを使用してください。

クイックリファレンス

認証チェックリスト

本番稼働前に確認:

キーフォーマットリファレンス

Public Test:    pkey_test_XXXXXXXXXXXXXXXXXXXX
Public Live:    pkey_live_XXXXXXXXXXXXXXXXXXXX
Secret Test:    skey_test_XXXXXXXXXXXXXXXXXXXX
Secret Live:    skey_live_XXXXXXXXXXXXXXXXXXXX
Chain:          chain_XXXXXXXXXXXXXXXXXXXX

概要​

APIキー​

キータイプ​

テストキー vs 本番キー​

テストキー（開発用）​

本番キー（プロダクション）​

APIキーの検索​

認証の仕組み​

認証の例​

cURLの使用​

Rubyの使用​

Pythonの使用​

PHPの使用​

Node.jsの使用​

Goの使用​

使用するキー​

公開鍵を使用する場合:​

秘密鍵を使用する場合:​

❌ 絶対にしないこと:​

セキュリティベストプラクティス​

1. キーを安全に保管​

✅ 良い例: 環境変数​

✅ 良い例: シークレット管理システム​

❌ 悪い例: ハードコードされたキー​

2. テストと本番を分離​

3. キーを定期的にローテーション​

4. キーの権限を制限​

5. キーの使用を監視​

認証エラー​

401 認証されていません​

403 Forbidden​

APIバージョニング​

認証のテスト​

アカウントエンドポイントでテスト​

よくある質問​

クイックリファレンス​

認証チェックリスト​

キーフォーマットリファレンス​

関連リソース​

概要