Skip to content

Credentials and keys

This page is for whoever puts a key into your app or your server. It explains the two credentials Monaiq gives you, where each comes from, and what happens when you revoke or replace.

The API key is the secret that authenticates your whole account to the Monaiq APIs. It is your server-side identity: the embedded checkout calls, the management API and the instance surfaces take it. Under Monaiq’s flat tenancy it is also the key your account sells with, so it belongs on a server you control and nowhere else. It never ships inside an application you distribute, and it is never part of an encoded credential.

The encoded credential is a single portable string that starts SIDUB_LIC_. It bundles the seat id, the service key id, the service key public member and a runtime token minted for that one seat into one value, so you configure one setting instead of four. Both SDKs take it directly, and it is the format the quickstarts use. The seat page calls it a license code.

The two are not interchangeable, and that is the point. An encoded credential authorizes and meters the one seat it names, and can do nothing else, which is what makes it safe to hand to a buyer and to install in an application you distribute. An API key is the account.

The JavaScript SDK also accepts the parts individually (seatId, serviceKeyId, serviceKeyPublicMember and runtimeToken) for cases where your configuration already holds them separately. They are the same four values the encoded string carries.

The payload carries Version, SeatId, ServiceKeyId, ServiceKeyPublicMember and RuntimeToken, and Version is 2. Decoders accept version 2 only: an older payload named the seat LicenseId and is refused, not reinterpreted. The runtime token is opaque to your application: it is a signed token the gateway validates. Never decode it, never parse it, never log or display it; pass it through as received.

The token has no expiry of its own. It lives as long as the seat it names, or until the credential is revoked.

An encoded credential comes from the seat it belongs to. Open the seat at monaiq.com/manage/licenses/{licenseId}/seats/{seatId}, and under Credentials name the machine or app in the optional Label field and press Issue license code. The value is shown once, at issue, and never again: copy it then. If you lose one, issue another and revoke the old one.

A purchase hands one back directly: a completed checkout result carries it as EncodedCredential, which is the value your application stores. See In-app purchase and Deliver to your customers.

The API key is at monaiq.com/manage/credentials. The page shows “Your API key”, and mints one for you the first time you visit, so there is no separate create step. That page is the key’s only home: the license page does not show it and does not replace it. Only an owner of the account sees the key there or replaces it; a member is told to ask an owner.

If you work through an assistant, the profile tool retrieves your account credentials as well. See AI-assisted setup.

Read the value from configuration rather than writing it into a file that is checked in.

  • .NET. Set LicensingServiceOptions.EncodedCredential from a configuration key. The .NET quickstart reads it from Licensing:EncodedCredential, so you can supply the real value from user secrets while you develop and from the host’s configuration in production without the code changing.
  • Node. Pass encodedCredential from the environment. The JavaScript SDK quickstart reads MONAIQ_CREDENTIAL.

There is nothing else to set. The SDK decodes the string, calls the runtime operations under {licenseServiceUri}/runtime and {consumptionServiceUri}/runtime, and presents the token as Authorization: Bearer for you.

Issue as many credentials per seat as you need, one per machine, per deployment or per environment, and label each one so a list of several is one you can act on. The seat page lists what exists: the short form of each code, its label, when it was issued, and whether it is live or revoked. A revoked row stays on the list, because removing it would leave you unable to tell “revoked” from “never issued”.

Revoke is per credential. The rest of the seat, and every other credential issued against it, keep working.

Everything the seat page does, the management API does too, for any seat your account issued. POST /licensing-mgmt/licenses/{licenseId}/seats/{seatId}/credentials issues one and returns the encoded credential (send a RequestId GUID of your own, and a retry answers the same credential rather than a second one), GET on the same path lists what the seat has, and DELETE /licensing-mgmt/licenses/{licenseId}/seats/{seatId}/credentials/{credentialId} revokes one. The calls take the account API key in dub-apiKey.

This is how you hand a credential to a customer at the moment they need one, rather than asking them to open the portal: provision the machine, issue a credential for it, install the value, and revoke it when the machine goes away. The Label you send is what tells the two apart later.

The same rule applies as on the seat page, and the API cannot soften it: the encoded credential comes back once, in the response to the issue that minted it. Store it then. A listing never returns it, and nothing can read it back. The wire contract is in the HTTP API reference.

The Credentials page in the portal offers two actions, and the rotate_api_key tool does the same from an assistant or any MCP client. Either way, only an owner of the account can use them.

  • Replace key gives you a new key and keeps the old one working for 24 hours while you update your app. Both keys work during that overlap, so you can move each deployment to the new key without an outage. The portal and the tool both say the exact time the old key stops, in UTC.
  • Revoke now gives you a new key and stops the old one at once. Use it if the key leaked. Your app stops working until you deploy the new key.

To replace the key:

  1. Press Replace key.
  2. Update every deployment, environment and machine that holds the old value with the new one.
  3. Finish before the overlap ends. Anything still holding the old value starts failing then.

With rotate_api_key you can set the overlap with overlapHours, from 0 to 168. overlapHours=0 stops the old key immediately, as Revoke now does.

Replacing again while an overlap is running ends that overlap at once: the key it was keeping alive stops, and the key you are replacing now gets a new overlap. Revoke now ends both.

Replace the key when it may have been exposed, when someone who had access to it leaves, or on whatever schedule your own policy sets.

Replacing the API key does not touch any encoded credential. The two are separate authorities, so a replacement does not invalidate what your buyers have installed.

When an application you distribute sells your offerings from inside itself, it ships with neither of the formats above. The buyer signs in with their Monaiq identity and the purchase is made with the buyer’s own token, so no seller key ships in the build: there is nothing in the binary to extract. The app reads your catalog anonymously and presents the buyer’s bearer only on the two checkout calls. In-app purchase covers the sign-in options and the client.

What the buyer receives at the end of that purchase is an encoded credential of their own, and it carries a runtime token for the seat they just bought, not a key of theirs and not a key of yours. It authorizes and meters that one seat, it can be revoked from the seat page on its own, and it reaches nothing else on the platform. Treat it as the secret it is, in the platform’s secure store rather than a log or a plain file, but a leak costs the buyer one revocable seat rather than their account.

A credential proves that the platform issued it for one seat. It does not, by itself, say which product that seat is for. Feature keys are short strings you choose, and nothing stops another seller from choosing the same ones, so an application that accepts a credential from its user (a desktop app, a CLI, a self-hosted service) would otherwise accept a credential bought for someone else’s product.

Set IssuerClientId (your account’s client id) and ProductId (this product’s id) in the SDK options, and the SDK sends them with every runtime call. The platform then refuses a seat of another seller or another product with 403 AuthorizationDenied and the reason ProductMismatch, and the SDK refuses an answer whose signed features name another seller. A backend that obtains its own seats through the seller API is not exposed to this, but should set both all the same: it costs nothing and closes the door for good.

If you bought a product rather than built one

Section titled “If you bought a product rather than built one”

Credentials for something you bought are on the seat’s detail page in your account, alongside its features (the license’s, the same on every seat) and your usage against them; the license carries the billing. See Your licenses.