> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gominerva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> How to create and manage Minerva API keys and screening workflow webhooks from the Developers page.

export const StorybookFrame = ({storyId, title, version = "20260419-1", height, zoom = 0.7, preferLocalPreview = false}) => {
  const HOSTED_STORYBOOK_BASE_URL = "https://minerva-storybook.s3.ca-central-1.amazonaws.com/iframe.html";
  const isLocalDocsPreview = typeof window !== "undefined" && ["localhost", "127.0.0.1"].includes(window.location.hostname);
  const storybookBaseUrl = preferLocalPreview && isLocalDocsPreview ? "http://localhost:6006/iframe.html" : HOSTED_STORYBOOK_BASE_URL;
  const params = new URLSearchParams({
    id: storyId,
    viewMode: "story",
    singleStory: "true",
    shortcuts: "false",
    toolbar: "0",
    nav: "0",
    panel: "0"
  });
  params.set("v", version);
  const src = `${storybookBaseUrl}?${params.toString()}`;
  const unscaledHeight = `${Math.ceil(height / zoom)}px`;
  const unscaledWidth = `${100 / zoom}%`;
  return <div style={{
    width: "100%"
  }}>
      <div style={{
    height: `${height}px`,
    overflow: "hidden",
    border: "1px solid #e2e8f0",
    borderRadius: "12px",
    backgroundColor: "#ffffff",
    display: "flex",
    justifyContent: "center",
    alignItems: "flex-start"
  }}>
        <iframe src={src} title={title} loading="lazy" style={{
    width: unscaledWidth,
    height: unscaledHeight,
    transform: `scale(${zoom})`,
    border: "0",
    display: "block",
    transformOrigin: "top center",
    flexShrink: 0
  }} allowFullScreen></iframe>
      </div>
    </div>;
};

Minerva API access is managed from the <strong>Developers</strong> page in the
Minerva dashboard.

**Access:** Requires the <strong>Developer</strong> role or above. In the
sidebar, go to <strong>Administration</strong> >

<strong>Developers</strong>.

Use this guide when you need to:

* create a new live or dev application key for an integration
* review existing application key prefixes, creators, and last-used activity
* deactivate or delete unused keys without affecting other integrations
* configure screening workflow webhooks for profile status updates

<Info>
  Create a separate application per environment, customer integration, or
  downstream service. That keeps key lifecycle actions, last-used timestamps,
  and audit context isolated for each integration.
</Info>

## Before You Begin

* confirm you have a <strong>Developer</strong>, <strong>Admin</strong>, or
  <strong>Owner</strong> team role
* decide whether the integration needs a <strong>Live</strong> or
  <strong>Dev</strong> 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
  <code>x-webhook-key</code> header

## Developers Page Overview

The Developers page combines two integration surfaces:

* <strong>API Keys</strong> for issuing and managing application credentials
* <strong>Webhooks</strong> for profile status update notifications

<StorybookFrame storyId="pages-administration-developers--default" title="Developers Page" height={820} />

## Create A New API Key

Minerva creates API keys through named applications.

When you select <strong>Create application</strong>, Minerva asks for:

* an application name
* an optional description so your team knows what the key is used for
* the application mode: <strong>Live</strong> or <strong>Dev</strong>

<StorybookFrame storyId="pages-administration-developers--create-application" title="Create Application" height={900} />

### What To Expect 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

<Tip>
  Use consistent application names such as
  <strong>Customer Gateway - Prod</strong>,
  <strong>Customer Gateway - QA</strong>, or
  <strong>Partner Sync - Sandbox</strong> so lifecycle actions stay obvious in
  audit and support workflows.
</Tip>

## 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

<StorybookFrame storyId="pages-administration-developers--manage-application" title="Manage Application" height={1220} />

## Screening Workflow Webhooks

Webhooks are currently for <strong>profile status update</strong> events only.
They are intended to support tighter integrations and near-real-time
notifications when you use <strong>Screening Workflow Profiles</strong>.

Supported profile status values today are:

* <code>potential\_match</code>
* <code>accepted</code>
* <code>rejected</code>

This is most useful when your internal systems need to react as Minerva
profiles move through review outcomes.

<Info>
  Webhooks do not replace the screening APIs. They complement a profile-based
  workflow by notifying your downstream systems when a Minerva profile changes
  status.
</Info>

### Create And Manage Webhooks

The Webhooks section lets you:

* name each webhook destination clearly
* choose which profile status values 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

<StorybookFrame storyId="pages-administration-developers--create-webhook" title="Create Webhook" height={860} />

## Best Practices

* create one application key per integration and environment instead of sharing
  a single key broadly
* 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 <code>x-webhook-key</code> header on every webhook delivery