Authentifizierung

Alle Proctorio-API-Anfragen erfordern eine Authentifizierung mit einem API Key. Ihr API Key identifiziert Ihre Integration und autorisiert den Zugriff auf Proctorio-Dienste.

Einen API Key erhalten

API Keys werden von Ihrem Proctorio-Account-Manager waehrend der Integrationseinrichtung bereitgestellt. Jeder Schluessel ist:

Mit dem Konto Ihrer Organisation verknuepft
Auf bestimmte Regionen beschraenkt (AU, CA, DE, EU, IN, JP, SA, SG, UK, US)
Fuer die Endpoints aktiviert, die Ihre Integration benoetigt

API Key-Format

Ihr API Key besteht aus zwei Teilen:

api_key = {consumer_key}{MD5(secret)}

Komponente	Beschreibung
`consumer_key`	Ihr eindeutiger Identifikator (bei der Einrichtung bereitgestellt)
`secret`	Ihr geheimer Schluessel (bei der Einrichtung bereitgestellt)
`MD5(secret)`	Der MD5-Hash Ihres geheimen Schluessels, in hexadezimaler Kleinschreibung

Schluesselformate, die Sie erhalten koennen

Abhaengig von Ihrer Integrationseinrichtung koennen Sie Anmeldedaten in einem von zwei Formaten erhalten:

Option 1: Vollstaendiger API Key — Eine einzelne vorberechnete Zeichenkette, die sofort verwendet werden kann:

a1b2c3d4e5f67890a1b2c3d4e5f678906286c281a69bb4cd781276f71da08d53

Option 2: Consumer Key + Secret — Zwei separate Werte, die Sie kombinieren:

Consumer Key: a1b2c3d4e5f67890a1b2c3d4e5f67890
Secret:       12345678abcdef0012345678abcdef00

Um den vollstaendigen API Key aus Option 2 zu berechnen:

Berechnen Sie den MD5-Hash Ihres geheimen Schluessels
Verketten Sie: {consumer_key}{md5_hash}

Beispiel: Berechnung des 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

Ihren API Key verwenden

Fuegen Sie Ihren API Key im api_key-Header jeder Anfrage ein:

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://..."}'

Header-Format

Header	Wert	Erforderlich
`api_key`	Ihr API Key	Ja
`Content-Type`	`application/json`	Ja (fuer POST-Anfragen)

Regionale Endpoints

Ihr API Key ist fuer bestimmte Regionen bereitgestellt. Verwenden Sie den regionalen Endpoint, der zu Ihrem Schluessel passt:

Region	Basis-URL
Australien	`https://au1.proctorapi.com`
Kanada	`https://ca1.proctorapi.com`
Deutschland	`https://de1.proctorapi.com`
Europa	`https://eu1.proctorapi.com`
Indien	`https://in1.proctorapi.com`
Japan	`https://jp1.proctorapi.com`
Suedafrika	`https://sa1.proctorapi.com`
Singapur	`https://sg1.proctorapi.com`
Vereinigtes Koenigreich	`https://uk1.proctorapi.com`
Vereinigte Staaten	`https://us1.proctorapi.com`

Die Verwendung der falschen Region gibt einen 401-Fehler mit dem Code 2155 - Incorrect region zurueck.

Fehlerantworten

Authentifizierungsfehler geben 401 Unauthorized mit einem dieser Codes zurueck:

Code	Nachricht	Bedeutung
2154	Konto nicht aktiv	Ihr Konto ist deaktiviert oder gesperrt
2155	Falsche Region	Der API Key ist fuer diesen regionalen Endpoint nicht gueltig
2655	Ungueltiger api_key	Der API Key fehlt, ist fehlerhaft oder wurde widerrufen

Bewährte Sicherheitspraktiken

Geben Sie Ihren API Key niemals preis in clientseitigem Code, oeffentlichen Repositories oder Browser-Anfragen
Verwenden Sie Umgebungsvariablen um Schluessel in Ihrer Serveranwendung zu speichern
Rotieren Sie Schluessel regelmaessig indem Sie einen neuen Schluessel bei Ihrem Account-Manager anfordern
Verwenden Sie separate Schluessel fuer Entwicklungs-/Staging- und Produktionsumgebungen
Ueberwachen Sie die Nutzung ueber Ihr Proctorio-Dashboard auf unerwartete Aktivitaeten

Beispiel: Verwendung von Umgebungsvariablen

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://...' })
});