Skip to main content
Minerva API access is managed from the Developers page (Administration > Developers in the sidebar). Each integration authenticates with its own application API key, and the page keeps the key prefix, creator, and last-used time for every application you create. Access: Requires the Developer role or above. Roles are assigned through your identity provider; see the SAML SSO and SCIM Guide for role mapping. This guide covers creating and reviewing application keys, deactivating or deleting unused keys, and configuring webhooks.
Create a separate application per environment, customer integration, or downstream service, rather than sharing one key across integrations. That keeps key lifecycle actions, last-used timestamps, and audit context isolated for each integration.

​
Before you begin

  • Confirm you have a Developer, Admin, or Owner team role.
  • Decide whether the integration needs a Live or Dev application key.
  • Prepare a vault or secrets manager to store any newly created API key.
  • If you plan to use webhooks, prepare an HTTPS endpoint that can validate the x-webhook-key header.

​
The Developers page

The page has two surfaces:
  • API Keys for issuing and managing application credentials
  • Webhooks for screening, identity verification, and onboarding notifications

​
Create a new API key

Minerva creates API keys through named applications. When you select Create application, Minerva asks for:
  • An application name
  • An optional description so your team knows what the key is used for
  • The application mode: Live or Dev

​
After creation

  • Each application receives its own key lifecycle and usage tracking
  • The new plaintext key is shown only once, so store it immediately in your secrets manager
  • The table then keeps the key prefix, creator, created timestamp, and last used timestamp for later review
Use consistent application names such as Customer Gateway - Prod, Customer Gateway - QA, or Partner Sync - Sandbox so lifecycle actions stay obvious in audit and support workflows.

​
Manage existing API keys

Open an application row to review and manage its details. The management view lets you:
  • Update the application name or description
  • Review the current key prefix and historical key records
  • Confirm who created the application
  • Deactivate an application to stop downstream use immediately
  • Reactivate or delete an application when appropriate

​
Webhooks

Webhooks notify your downstream systems when something changes in your workspace. Minerva supports three kinds:
  • Screening profile status updates when a profile moves through screening and review.
  • Identity verification lifecycle events when an IDV session progresses through capture, assessment, and review.
  • Profile onboarding events when a combined screening and identity verification run changes state or completes.
The Webhooks reference lists the subscribable values for each kind, the payload shapes, delivery retries, and dedupe guidance.
Use the IDV Integration Guide when you need to create verification sessions for your customers, deliver invite emails, and react to verification results.
Use webhooks when your internal systems need to react as profiles and verification sessions move forward.
Webhooks do not replace the screening or identity verification APIs. They complement them by notifying your downstream systems when state changes, while the APIs remain the source of truth for the details.

​
Create and manage webhooks

The Webhooks section lets you:
  • Name each webhook destination clearly
  • Choose which events should trigger notifications
  • Copy the generated webhook key for receiver-side validation
  • Test the destination before relying on it in production
  • Edit or delete old destinations as integrations change

​
Best practices

  • Rotate or deactivate keys when an integration is retired or ownership changes
  • Store API keys and webhook keys in a secrets manager, not in source control
  • Use webhook names that identify the receiving system and environment clearly
  • Validate the x-webhook-key header on every webhook delivery