For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.

Install a License Key in Ops Manager

Installs a signed license key file in an Ops Manager installation to add coverage after you generate a license key in the Key Portal. If Ops Manager accepts the license key, it recalculates the license key status and returns it, and records a License installed audit event.

Required Roles

To access this resource, your API key must have the Global Owner role. The Global Owner role is the highest role in Ops Manager. Only users with this role can view and manage license keys.

Request

Send a PUT request with the license key file contents as the body.

Base URL: https://{OPSMANAGER-HOST}:{PORT}/api/public/v1.0

PUT /admin/licenses

Request Path Parameters

This endpoint doesn't use HTTP request path parameters.

Request Query Parameters

This endpoint accepts the following query parameters:

Name
Type
Necessity
Description
Default

pretty

boolean

Optional

Flag indicating whether the response body is in a prettyprint format.

false

envelope

boolean

Optional

Flag that indicates whether to wrap the response in an envelope.

Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query.

For endpoints that return one result, the response body includes:

  • status: HTTP response code

  • content: Expected response body

false

Request Body Parameters

Send the contents of the license key file as the request body. Set the Content-Type header to application/json. The endpoint doesn't use named body parameters.

Response

If Ops Manager accepts the license key, the response contains the recalculated license key status. The response contains the following fields:

Field
Type
Description

enforcement

object

Aggregated license key status of the Ops Manager installation. This field is null until Ops Manager calculates the status for the first time.

enforcement.effectiveState

string

License key state of the installation. Ops Manager returns one of LICENSED, GRACE, EXPIRED, or UNLICENSED. To learn how the states map to the Ops Manager interface, see Ops Manager License Keys Overview.

enforcement.cause

string

Identifies what produced the effectiveState value.

enforcement.enforced

boolean

Indicates whether the state is EXPIRED or UNLICENSED. Ops Manager doesn't restrict any operation in these states.

enforcement.transition

object

Next scheduled change to the license key state. This field is null when no change is scheduled.

enforcement.transition.evaluatorId

string

Evaluator that drives the next change.

enforcement.transition.inStateUntil

string

Date and time when the current state ends.

enforcement.transition.nextState

string

State that follows the current state.

enforcement.warnings

array of objects

Warnings that are open. Ops Manager opens a renewal warning before your order end date. To learn more, see Ops Manager License Keys Overview.

enforcement.warnings[n].evaluatorId

string

Evaluator that raised the warning.

enforcement.warnings[n].since

string

Date and time when the warning opened.

enforcement.warnings[n].subjects

array of objects

Subjects that the warning covers. Each object contains an id and a since date. This array is empty when the warning applies to the whole installation.

enforcement.verdicts

array of objects

Contribution of each evaluator to the effectiveState value.

enforcement.verdicts[n].evaluatorId

string

Evaluator that produced the verdict.

enforcement.verdicts[n].state

string

State that the evaluator calculated.

enforcement.verdicts[n].breachAt

string

Date and time when the breach takes effect, such as the order end date. This date is in the future while the state is LICENSED.

enforcement.verdicts[n].warningStart

string

Date and time when the renewal warning window opens. This field is null unless the verdict state is LICENSED.

enforcement.verdicts[n].metadata

object

Details that are specific to the evaluator. This field is null for evaluators that provide none.

enforcement.verdicts[n].transition

object

Next change to the verdict state. The object contains inStateUntil and nextState fields. This field is null when no change is scheduled.

licenses

array of objects

License keys that are installed on the Ops Manager installation.

licenses[n].artifactId

string

Unique identifier of the license key. Use this value to release the license key. The Ops Manager interface shows this value as the license key ID.

licenses[n].usable

boolean

Indicates whether Ops Manager can use the license key for coverage.

licenses[n].generatedAt

string

Date and time when MongoDB generated the license key.

licenses[n].installedAt

string

Date and time when the license key was installed.

licenses[n].status

string

Status of the license key. Ops Manager returns one of ACTIVE, EXPIRED, RELEASED, or DENIED. A license key is ACTIVE when it is usable and its order end date is in the future. A license key is EXPIRED when it is usable but its order end date passed.

licenses[n].statusCause

string

Reason code for a DENIED license key. Ops Manager returns one of CLAIM_CONFLICT, CLAIM_REVOKED, or VERIFICATION_FAILED. Ops Manager sets this field only for a DENIED license key.

licenses[n].statusReason

string

Sentence that describes why the license key is DENIED. Ops Manager sets this field only for a DENIED license key.

licenses[n].termEnd

string

Date and time when the coverage of the license key ends. This field is null when the license key has no end date.

licenses[n].grants

array of objects

Grants that the license key contains. For a RELEASED or DENIED license key, Ops Manager returns the grants if the stored license key still passes verification. This array is empty when verification fails.

licenses[n].grants[n].grantType

string

Type of the grant, such as contract.

licenses[n].grants[n].grantId

string

Identifier of the grant. This field is null when the issuer doesn't set it.

licenses[n].grants[n].startDate

string

Date and time when the grant starts.

licenses[n].grants[n].endDate

string

Date and time when the grant ends.

licenses[n].grants[n].entitlements

array of objects

Entitlements that the grant carries. Each object uses the fields described for activeEntitlements.

activeEntitlements

object

Entitlements that are active now, grouped by entitlement type. Each key is an entitlement type, such as exemption::telemetry. Each value is an array of entitlement objects.

activeEntitlements.<type>[n].type

string

Entitlement type.

activeEntitlements.<type>[n].productName

string

Product name that the entitlement applies to. This field is null when the entitlement has no product name.

activeEntitlements.<type>[n].active

boolean

Indicates whether the entitlement is in effect.

activeEntitlements.<type>[n].window

object

Validity window of the entitlement. The object contains start and end date fields. This field is null when the window has no bounds.

Errors

If Ops Manager rejects the license key, the response has the HTTP status from the following table. The errorCode field of the response body contains the error code, and the detail field contains the message.

The messages use the word artifact to refer to a license key.

Error Code
HTTP Status
Message

ARTIFACT_MALFORMED

400

This file could not be read. It may be corrupted or was modified after signing. Contact your MongoDB account team to obtain a replacement.

ARTIFACT_SIGNATURE_INVALID

400

This file cannot be verified - it may have been modified after signing. Contact your MongoDB account team to obtain a replacement.

ARTIFACT_UNTRUSTED

400

This file was signed for a different version of Ops Manager or by an untrusted key. Contact your MongoDB account team for a compatible file.

ARTIFACT_CERTIFICATE_INVALID

400

This file's signing certificate is not valid for this Ops Manager. Contact your MongoDB account team to obtain a replacement.

ARTIFACT_HOLDER_NOT_ALLOWED

403

This artifact is bound to specific Ops Manager instances and cannot be installed on this one. Contact your MongoDB account team.

ARTIFACT_OUTDATED

409

This artifact is not newer than one already installed on this Ops Manager. Install the latest artifact issued by your MongoDB account team.

Example Request

Use curl to send a PUT request to the /admin/licenses endpoint:

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \     --header "Accept: application/json" \     --header "Content-Type: application/json" \     --include \     --request PUT \     "https://<OpsManagerHost>:<Port>/api/public/v1.0/admin/licenses?pretty=true" \     --data @{LICENSE-KEY-FILE}

Example Response

The following examples show the response headers and the response body of a successful request.

Response Header

The following headers show an unauthorized response and a successful response:

HTTP/1.1 401 UnauthorizedContent-Type: application/json;charset=ISO-8859-1Date: {dateInUnixFormat}WWW-Authenticate: Digest realm="MMS Public API", domain="", nonce="{nonce}", algorithm=MD5, op="auth", stale=falseContent-Length: {requestLengthInBytes}Connection: keep-alive
HTTP/1.1 200 OKVary: Accept-EncodingContent-Type: application/jsonStrict-Transport-Security: max-age=300Date: {dateInUnixFormat}Connection: keep-aliveContent-Length: {requestLengthInBytes}X-MongoDB-Service-Version: gitHash={gitHash}; versionString={ApplicationVersion}

Response Body

The following example shows the response body:

{  "enforcement": {    "effectiveState": "LICENSED",    "cause": "term:LICENSED",    "enforced": false,    "transition": {      "evaluatorId": "term",      "inStateUntil": "2027-06-30T00:00:00Z",      "nextState": "GRACE"    },    "warnings": [],    "verdicts": [      {        "evaluatorId": "term",        "state": "LICENSED",        "breachAt": "2027-06-30T00:00:00Z",        "warningStart": "2027-02-28T00:00:00Z",        "metadata": null,        "transition": {          "inStateUntil": "2027-06-30T00:00:00Z",          "nextState": "GRACE"        }      }    ]  },  "licenses": [    {      "artifactId": "{ARTIFACT-ID}",      "usable": true,      "generatedAt": "2026-10-01T12:00:00Z",      "installedAt": "2026-11-04T15:30:00Z",      "status": "ACTIVE",      "statusCause": null,      "statusReason": null,      "termEnd": "2027-06-30T00:00:00Z",      "grants": [        {          "grantType": "contract",          "grantId": "{GRANT-ID}",          "startDate": "2026-07-01T00:00:00Z",          "endDate": "2027-06-30T00:00:00Z",          "entitlements": []        }      ]    }  ],  "activeEntitlements": {}}

Example Error Response

The following example shows the response body when Ops Manager rejects the license key:

{  "error": 409,  "reason": "Conflict",  "detail": "This artifact is not newer than one already installed on this Ops Manager. Install the latest artifact issued by your MongoDB account team.",  "errorCode": "ARTIFACT_OUTDATED",  "parameters": []}
Back
Get Status
Next
Release
Rate this page

On this page