ChatGPTで開く
Markdownで表示

認証

すべてのProctorio APIリクエストには、API keyを使用した認証が必要です。API keyは統合を識別し、Proctorioサービスへのアクセスを承認します。

API Keyの取得

API keyは、統合セットアップ時にProctorioアカウントマネージャーによって提供されます。各キーは以下の通りです：

  • 組織のアカウントに紐づけられています
  • 特定のリージョンに限定されています（AU、CA、DE、EU、IN、JP、SA、SG、UK、US）
  • 統合に必要なendpointsに対して有効化されています

API Keyの形式

API keyは2つの部分で構成されています：

api_key = {consumer_key}{MD5(secret)}
コンポーネント説明
consumer_key一意の識別子（セットアップ時に提供）
secretシークレットキー（セットアップ時に提供）
MD5(secret)シークレットのMD5ハッシュ（小文字の16進数形式）

受け取る可能性のあるキー形式

統合セットアップに応じて、2つの形式のいずれかで認証情報を受け取る場合があります：

オプション1：完全なAPI Key — すぐに使用できる事前計算済みの文字列：

a1b2c3d4e5f67890a1b2c3d4e5f678906286c281a69bb4cd781276f71da08d53

オプション2：Consumer Key + Secret — 組み合わせる2つの個別の値：

Consumer Key: a1b2c3d4e5f67890a1b2c3d4e5f67890
Secret:       12345678abcdef0012345678abcdef00

オプション2から完全なAPI keyを計算するには：

  1. シークレットのMD5ハッシュを計算します
  2. 連結します：{consumer_key}{md5_hash}

例：API Keyの計算

import hashlib

consumer_key = "a1b2c3d4e5f67890a1b2c3d4e5f67890"
secret = "12345678abcdef0012345678abcdef00"

# Compute MD5 hash of secret
md5_hash = hashlib.md5(secret.encode()).hexdigest()
# md5_hash = "6286c281a69bb4cd781276f71da08d53"

# Combine to form API key
api_key = consumer_key + md5_hash
# Result: a1b2c3d4e5f67890a1b2c3d4e5f678906286c281a69bb4cd781276f71da08d53
import { createHash } from 'crypto';

const consumerKey = 'a1b2c3d4e5f67890a1b2c3d4e5f67890';
const secret = '12345678abcdef0012345678abcdef00';

// Compute MD5 hash of secret
const md5Hash = createHash('md5').update(secret).digest('hex');
// md5Hash = "6286c281a69bb4cd781276f71da08d53"

// Combine to form API key
const apiKey = consumerKey + md5Hash;
// Result: a1b2c3d4e5f67890a1b2c3d4e5f678906286c281a69bb4cd781276f71da08d53

API Keyの使用

すべてのリクエストのapi_keyヘッダーにAPI keyを含めてください：

curl -X POST https://us1.proctorapi.com/v2/candidate/launch \
  -H "api_key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"launch_url": "https://..."}'

ヘッダー形式

ヘッダー値必須
api_keyお使いのAPI keyはい
Content-Typeapplication/jsonはい（POSTリクエストの場合）

リージョン別エンドポイント

API keyは特定のリージョン向けにプロビジョニングされています。キーに対応するリージョンのendpointを使用してください：

リージョンベースURL
オーストラリアhttps://au1.proctorapi.com
カナダhttps://ca1.proctorapi.com
ドイツhttps://de1.proctorapi.com
ヨーロッパhttps://eu1.proctorapi.com
インドhttps://in1.proctorapi.com
日本https://jp1.proctorapi.com
南アフリカhttps://sa1.proctorapi.com
シンガポールhttps://sg1.proctorapi.com
イギリスhttps://uk1.proctorapi.com
アメリカ合衆国https://us1.proctorapi.com

間違ったリージョンを使用すると、コード2155 - Incorrect regionの401エラーが返されます。

エラーレスポンス

認証の失敗は、以下のコードのいずれかと共に401 Unauthorizedを返します：

コードメッセージ意味
2154アカウントが有効ではありませんアカウントが無効化または停止されています
2155リージョンが正しくありませんAPI keyはこのリージョンのendpointでは有効ではありません
2655無効なapi_keyAPI keyが欠落しているか、形式が不正であるか、取り消されています

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

  • API keyを公開しないでください クライアントサイドのコード、公開リポジトリ、またはブラウザリクエストに含めないでください
  • 環境変数を使用してください サーバーアプリケーションにキーを保存するために
  • 定期的にキーをローテーションしてください アカウントマネージャーに新しいキーをリクエストしてください
  • 別々のキーを使用してください 開発/ステージング環境と本番環境で
  • 使用状況を監視してください Proctorioダッシュボードで予期しないアクティビティがないか確認してください

例：環境変数の使用

import os
import requests

API_KEY = os.environ.get('PROCTORIO_API_KEY')

response = requests.post(
    'https://us1.proctorapi.com/v2/candidate/launch',
    headers={
        'api_key': API_KEY,
        'Content-Type': 'application/json'
    },
    json={'launch_url': 'https://...'}
)
const API_KEY = process.env.PROCTORIO_API_KEY;

const response = await fetch('https://us1.proctorapi.com/v2/candidate/launch', {
  method: 'POST',
  headers: {
    'api_key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ launch_url: 'https://...' })
});