The admin application key
An admin application key is a tenant-wide key that can create, update, archive, and delete workspaces, and edit every workspace’s configuration through the API. In the Minerva dashboard it appears as the Admin (tenant-wide) key type.- Only an Owner or Admin can create, edit, rotate, deactivate, or delete an admin key. Developers see the Admin (tenant-wide) option disabled, with a hint to ask an owner or admin.
- The key acts only while the person who created it is still an owner or admin of the organization. If that person is demoted, disabled, or removed, every Workspace Management API request made with the key is refused with
403from the next request onward. Create a replacement key from an account that still holds the role. - The admin role can be set only when the key is created. You cannot change an existing workspace-scoped or tenant-scoped key into an admin key: that request returns
400with the message “Admin role can only be set when an application is created. Create a new admin application instead.” - The key belongs to one organization. It is never accepted for another organization’s
orgId. - Changes made with an admin key are recorded in the audit trail under the application’s name, not under a person.
- The Workspace Management API does not cover team management or SSO and SCIM settings. Those stay dashboard-only. Profiles and searches have their own APIs, which an admin key can also call for one workspace at a time. See One workspace per client.
Create an admin key
- Sign in as an Owner or Admin and open Administration > Developers.
- On API keys, select Create application.
- Enter a name and an optional description, and choose Live mode. Admin keys can’t be created in Dev mode.
- Under Scope, choose Admin (tenant-wide). Minerva sets Mode to Live and shows “Admin keys are always Live.”
- Create the application and copy the key. Minerva shows the plaintext key only once.
Authentication and base URL
Send every request tohttps://api.gominerva.com. Workspace paths start with /workspaces/v2/organizations/{orgId}, and custom-list activation paths start with /custom-lists/v2/organizations/{orgId}:
admin-api.gominerva.com is deprecated for API clients. It keeps working for
now, but new and updated integrations should call api.gominerva.com. The
paths change as well as the host:admin-api.gominerva.com/v2/organizations/{orgId}/custom-lists/…becomesapi.gominerva.com/custom-lists/v2/organizations/{orgId}/…admin-api.gominerva.com/v2/organizations/{orgId}/workspaces/…becomesapi.gominerva.com/workspaces/v2/organizations/{orgId}/…admin-api.gominerva.com/v2/webhooks/screening/…becomesapi.gominerva.com/webhooks/v2/screening/…
Authorization header. The legacy x-api-key header is also accepted.
orgId is your organization ID, and it must be the organization the key was created in.
Successful responses wrap the record in a data envelope that echoes the organization ID:
Endpoints
The Admin Actions - Endpoints reference in this tab, starting at List workspaces, lists every request and response field. The tables below summarize what each family does.Workspaces
POSTrequiresnameand accepts the same configuration sections asPATCH, such asmonitoringFeedFrequencies,monitoringRiskFrequencies,matchScoring,automaticDisposition, andriskInference.clientRiskRatingis accepted onPATCHonly.PATCHis sparse at the top level. A section you omit keeps its stored value. A section you send replaces that section, so send the completemonitoringFeedFrequenciesmap you want to keep.- Unknown fields are rejected with
400. - Archive a workspace with
PATCHand{"archived": true}before you delete it. The default workspace cannot be archived or deleted.
Profile groups
POSTrequiresname(up to 160 characters) andpriority.description(up to 4,000 characters) andmonitoringFeedFrequenciesare optional.priorityis an integer from0to1000000. Higher values win when a profile belongs to several groups, and each priority can be used by only one active group in a workspace. Reusing one returns409.- A group
PATCHthat carriesmonitoringFeedFrequenciesreplaces the group’s whole cadence map. Include every feed you want the group to keep. DELETEarchives the group rather than erasing it, so profiles that still reference it keep an auditable assignment.
Presets
configTypeismatch_scoringoralert_suppression. A preset body carriesconfigType,label, an optionaldescription, and theconfigobject.- A promotion body names
configType,targetWorkspaceId, and an optionalchangeSummary. Promotion also acceptscustomer_risk_rating, in which casepresetIdis a CRR scorecard ID.
Customer Risk Rating
Profile custom fields
Profile custom fields are defined once for the whole organization. Manage the definitions athttps://api.gominerva.com/tenant-config/v1/profile-custom-fields, which accepts any application key for your organization, including an admin key. The organization comes from the key, so these paths carry no organization or workspace ID. An admin key must also send the x-workspace-id header with the ID of any workspace in your organization, or the request returns 400; the definitions stay organization-wide.
These responses wrap the record in
result, with a message, not in the data envelope above. The Profile Custom Fields API page describes the definition fields, the field types, and how values are written on profiles.
Custom-list activation and entitlements
An admin key can read your custom-list entitlements and switch lists on or off in a workspace. To create lists, sync records, publish versions, and track deployment, see the Custom Lists API.
The activation body takes
enabled (default true). When you switch a list on, feedCategory and versionId are required so the list is bound to the feed and published version you intend.
Monitoring cadences
Monitoring cadences decide how often each data feed rescreens a profile. You set them per feed (Sanctions, PEP, News, Legal, Criminal, Internal) in a monitoringFeedFrequencies map, on a workspace and on each profile group. In the dashboard, News appears as Adverse Media and Internal as Internal Risk. A workspace can also set cadences per risk tier in monitoringRiskFrequencies (low, medium, high), which apply to profiles with that customer risk rating.
How a profile’s cadence is resolved
Minerva resolves each feed on its own.- Minerva orders the profile’s active groups by
priority, highest first. - It checks the groups in that order. The first group that sets a cadence for the feed, including
never, decides the feed for the groups. - A group set to
unsetpasses the decision to the next group down. - If every group is set to
unset, the risk tier decides. If the risk tier sets no cadence for the feed, the feed isnever. It does not fall back to the workspace cadence. - If the highest-priority group leaves the feed empty, the profile uses its risk-tier cadence, or the workspace cadence when the risk tier sets none. Once a group has passed the decision down with
unset, a lower group that leaves the feed empty is skipped too.
neverbeatsunset. A group set toneverdecides the feed, so a lower group cannot turn it back on. Only a risk tier that outranks the group can.- Empty and
unsetare different. Empty on the top group means “use the risk tier or workspace cadence”.unsetmeans “let a lower group or the risk tier decide, and otherwise do not monitor”.
unset is valid only on profile groups. Sending it in a workspace’s
monitoringFeedFrequencies or in monitoringRiskFrequencies returns 400.
Use never there to stop monitoring a feed.Example: combining two groups
Group A monitors Sanctions daily and leaves every other feedunset:
unset:
A profile only in group A, with no risk-tier cadence, is monitored for Sanctions daily and nothing else.
Errors
Most error responses carry the message as a plain string in the body. Custom-list activation can also return a JSON object witherror and message fields, as the 409 and 422 rows below describe. When the response’s Content-Type is application/json, parse the body as JSON.
Walkthrough: set up a new workspace
This walkthrough creates a workspace, adds the two groups from the example above, adjusts their priorities, and assigns a profile to both. Set these variables first:1. Create the workspace
The workspace monitors Sanctions and PEP weekly for profiles that are not in any group.cURL
201 with the new workspace in data.workspace. Keep data.workspace.id as WORKSPACE_ID.
2. Create two profile groups
cURL
cURL
201 with the group in data.profileGroup. Keep the two IDs as GROUP_A_ID and GROUP_B_ID.
3. Set priorities
Priority decides which group is checked first. Raise group B above group A with aPATCH that carries only priority, so the group’s cadences are left as they are:
cURL
unset for the other group’s feed. Priority matters when two groups both set a cadence for the same feed. These priorities are below every risk-tier priority, so a risk-tier cadence for the profile’s rating would still win. Use a priority above 1000 if a group must override risk tiers.
4. Assign a profile to both groups
Profile assignment is part of profile management, onhttps://api.gominerva.com/clm/v1, not the Admin API. You can use the same admin key and name the workspace in the x-workspace-id header, or use a workspace-scoped key created for the new workspace:
cURL
One workspace per client: the full API chain
If you serve several clients of your own, you can give each one its own workspace and run their whole monitoring setup with a single admin key. The admin key is tenant-wide, so every call outside the Workspace Management API names the client’s workspace in thex-workspace-id header.
The chain below creates the workspace, adds profile groups, creates and screens a monitored profile, reads its matches, assigns its groups, and reads its screening history. A workspace is usable as soon as the create call returns. There is no propagation delay.
The examples send the key in the Authorization: Api-Key header. Every endpoint in the chain also accepts the x-api-key header used elsewhere in these docs.
1. Create the client’s workspace
cURL
data.workspace.id from the 201 response as WORKSPACE_ID.
A new workspace starts as a copy of your default workspace’s onboarding feeds, monitoring cadences, allowed feeds, match scoring, and custom lists. Anything you send in the create call replaces the copied value. Check the copied onboarding feeds before you onboard profiles: if they leave out a feed you need, such as Sanctions, set them as shown above or name the feeds on each onboarding call.
2. Create profile groups in it
cURL
data.profileGroup.id as GROUP_ID. See Profile groups for the cadence fields a group can carry.
3. Create and screen a monitored profile
You can create and screen a profile in one call, or create it first and screen it later. Use one of the following alternatives for the same subject.Create and screen in one call
POST /clm/v1/onboarding/profiles creates the profile and screens it in the same call:
cURL
201 response carries the profile in result.profile, including its screened status, and any review tasks in result.tasks. Keep result.profile.id as PROFILE_ID.
Create first, then screen the existing profile
First, create a monitored profile without screening it:cURL
result.profile.id from the 201 response as PROFILE_ID. The profile starts with status not_screened.
To screen that existing profile, send the onboarding request shown above with the same externalId and the same x-workspace-id. Minerva returns the same profile ID, applies the screening result to the profile, and returns any review tasks. Without the same external reference in the same workspace, the request does not select that existing profile and can create a second one. The example explicitly disables identity verification so this is a screening-only request.
If you do not screen it through onboarding, each feed’s first scheduled monitoring screening waits until its cadence interval has passed since the profile was created. For a monthly feed that is about a month later.
A direct Core search with
profile_id associates the search and its stored
matches with the profile for history retrieval. It does not update the
profile’s screening status or last-screening fields, or trigger the profile
screening workflow. Use the onboarding endpoint above to screen an existing
profile and update that workflow.4. Fetch the profile’s matches
cURL
matches[]. Each one carries the request_id of the screening that produced it.
5. Assign profile groups
cURL
profileGroupIds replaces the profile’s whole group list.
- Minerva rejects an ID that does not match an active group in this workspace with
400. That covers unknown IDs and groups from another workspace. - An ID that is already on the profile can be sent again even if that group has since been archived, so you can resend the full list without removing it first.
profileGroupIds in the step 3 create call.
6. Read the profile’s screening history
cURL
requests[] is one screening of the profile, including runs that found nothing. See Monitoring run history.
Workspace scoping rules
These rules apply to the profile, search, and match APIs above.Related documentation
- API Keys for creating and managing application keys
- Profile Groups API for assigning and filtering profiles by group
- Workspaces Guide for workspace-scoped and tenant-wide settings
- Screening Frequencies Guide for the dashboard view of monitoring cadences