Authentication

All Proctorio API requests require authentication using an API key. Your API key identifies your integration and authorizes access to Proctorio services.

Getting an API Key

API keys are provisioned by your Proctorio account manager during integration setup. Each key is:

Tied to your organization's account
Scoped to specific regions (AU, CA, DE, EU, IN, JP, SA, SG, UK, US)
Enabled for the endpoints your integration requires

API Key Format

Your API key is composed of two parts:

api_key = {consumer_key}{MD5(secret)}

Component	Description
`consumer_key`	Your unique identifier (provided during setup)
`secret`	Your secret key (provided during setup)
`MD5(secret)`	The MD5 hash of your secret, in lowercase hexadecimal

Key Formats You May Receive

Depending on your integration setup, you may receive credentials in one of two formats:

Option 1: Full API Key — A single pre-computed string ready to use:

a1b2c3d4e5f67890a1b2c3d4e5f678906286c281a69bb4cd781276f71da08d53

Option 2: Consumer Key + Secret — Two separate values that you combine:

Consumer Key: a1b2c3d4e5f67890a1b2c3d4e5f67890
Secret:       12345678abcdef0012345678abcdef00

To compute the full API key from Option 2:

Calculate the MD5 hash of your secret
Concatenate: {consumer_key}{md5_hash}

Example: Computing the 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

Using Your API Key

Include your API key in the api_key header of every request:

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	Value	Required
`api_key`	Your API key	Yes
`Content-Type`	`application/json`	Yes (for POST requests)

Regional Endpoints

Your API key is provisioned for specific regions. Use the regional endpoint that matches your key:

Region	Base URL
Australia	`https://au1.proctorapi.com`
Canada	`https://ca1.proctorapi.com`
Germany	`https://de1.proctorapi.com`
Europe	`https://eu1.proctorapi.com`
India	`https://in1.proctorapi.com`
Japan	`https://jp1.proctorapi.com`
South Africa	`https://sa1.proctorapi.com`
Singapore	`https://sg1.proctorapi.com`
United Kingdom	`https://uk1.proctorapi.com`
United States	`https://us1.proctorapi.com`

Using the wrong region returns a 401 error with code 2155 - Incorrect region.

Error Responses

Authentication failures return 401 Unauthorized with one of these codes:

Code	Message	Meaning
2154	Account not active	Your account is disabled or suspended
2155	Incorrect region	API key is not valid for this regional endpoint
2655	Invalid api_key	The API key is missing, malformed, or revoked

Security Best Practices

Never expose your API key in client-side code, public repositories, or browser requests
Use environment variables to store keys in your server application
Rotate keys periodically by requesting a new key from your account manager
Use separate keys for development/staging and production environments
Monitor usage through your Proctorio dashboard for unexpected activity

Example: Environment Variable Usage

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