API Keys

API keys allow you to interact with Prosopo services programmatically — for example, managing access control rules, querying traffic data, or verifying CAPTCHA solutions from your backend without using the portal UI.

API key management is available to accounts with the API feature enabled. Check your account’s feature flags in the portal.

Creating an API Key

Section titled Creating an API Key

1. Log in to the Prosopo Portal
2. Navigate to API Keys from the main menu
3. Click Create API Key
4. Fill in the required fields:
   • Name (required): A descriptive label for the key, e.g. “Production Backend” or “CI/CD Pipeline”
   • Expiration Time (optional): Time in seconds until the key expires. Leave empty for a key that does not expire.
   • Permissions (required): Select which operations this key can perform (see below)
5. Click Create API Key

After creation, the full API key is displayed once. Copy it immediately — it cannot be retrieved later.

Permissions

Section titled Permissions

Each API key is scoped to a specific set of permissions. Only grant the permissions the key actually needs.

Access Rules

Section titled Access Rules

Permission	Description
getRules	List access control rules
getSuggestion	Get a single rule suggestion
getSuggestions	List rule suggestions
applySuggestions	Apply suggested rules
createRule	Create a new access control rule
deleteRule	Delete an access control rule
deleteRuleGroup	Delete an access control rule group

Sites

Section titled Sites

Permission	Description
getSite	Get a single site’s details
getSites	List all sites
createSite	Create a new site
deleteSite	Delete a site
updateSite	Update site settings

API Keys

Section titled API Keys

Permission	Description
getApiKeys	List API keys
createApiKey	Create a new API key
updateApiKey	Update an existing API key
deleteApiKey	Delete an API key

Users

Section titled Users

Permission	Description
getUsers	List team members
createUser	Invite a new team member
updateUser	Update a team member’s role
deleteUser	Remove a team member

Traffic

Section titled Traffic

Permission	Description
getTraffic	Query traffic analytics data

Verify

Section titled Verify

Permission	Description
verify	Verify CAPTCHA solutions

Search Captcha Records

Section titled Search Captcha Records

Permission	Description
searchCaptchaRecords	Search and retrieve CAPTCHA audit records

Using an API Key

Section titled Using an API Key

Include the API key in the Authorization header of your HTTP requests:

curl -X GET https://api.prosopo.io/v1/prosopo/provider/admin/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Or in code:

const response = await fetch('https://api.prosopo.io/v1/prosopo/provider/admin/rules', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
});

Managing API Keys

Section titled Managing API Keys

Viewing Keys

Section titled Viewing Keys

The API Keys page shows all keys for your account:

• Name: The label you gave the key
• Created: When the key was created
• Expires: When the key expires (or “Never” for non-expiring keys)
• Permissions: Which operations the key can perform

Deleting Keys

Section titled Deleting Keys

To revoke an API key, click the delete button next to it in the API Keys list. The key is immediately invalidated — any requests using it will be rejected.

Deletion is permanent and cannot be undone. If you delete a key by mistake, create a new one and update your application with the new key.

Security Best Practices

Section titled Security Best Practices

Principle of Least Privilege

Section titled Principle of Least Privilege

Only grant the permissions each key actually needs. A key used solely for CAPTCHA verification should only have the verify permission — it does not need createSite or deleteRule.

Use Expiring Keys for Temporary Access

Section titled Use Expiring Keys for Temporary Access

When granting access to a contractor, CI/CD pipeline, or temporary integration, set an expiration time so the key is automatically invalidated.

Rotate Keys Regularly

Section titled Rotate Keys Regularly

For long-lived production keys, rotate them periodically:

1. Create a new key with the same permissions
2. Update your application to use the new key
3. Verify the new key works
4. Delete the old key

Never Expose Keys Client-Side

Section titled Never Expose Keys Client-Side

API keys should only be used in server-side code. Never embed them in frontend JavaScript, mobile apps, or public repositories. For client-side CAPTCHA integration, use site keys instead — see Client-side Rendering.

Monitor Usage

Section titled Monitor Usage

Review the Audit page and traffic analytics to detect any unexpected API key usage patterns that could indicate a compromised key.