Check a license without installing it
POST /admin/license/validate
Runs the checks an install would run on a license and returns the status it would give, without installing it. Nothing is written and the license in use doesn’t change.
Send the license text as license_text in a JSON body, exactly as
issued; this isn’t a file upload. The server checks the format, the
signature against its built-in list of signing keys, the issuer and
the validity dates. If the license is tied to an organization key,
it also reads this server’s org.key and checks that it matches.
Nothing is sent to a license server.
On success you get the status the license would give, with loaded
true and, when a license path is set, path showing where an
install would write it. Passing doesn’t mean an install will work:
if AA_LICENSE_PATH is set to an empty value, path is left out
and an install with POST /admin/license/upload is refused with a
409. A license that fails any check gets a 400 whose code says
which one. You need system.admin.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”The license to check or install: the full text of the .lic file,
exactly as issued.
object
The whole license, from -----BEGIN ARTIST-ALLEY LICENSE----- to
-----END ARTIST-ALLEY LICENSE-----. Blank lines, indentation and
the order of the lines inside don’t matter, but no value may change.
Responses
Section titled “ Responses ”The license passed every check. It isn’t installed.
The license state. loaded false means community mode: no license
is in use and the built-in community features apply. Commercial
licensing is planned but not offered today, so installs run in
community mode.
Fields that don’t apply are left out rather than sent as null.
object
True when the license passed every check: it’s in use or, in a response from POST /admin/license/validate, it would be. False means community mode.
community without a license. Otherwise the tier the license names,
such as pro or enterprise, which belong to the planned licensing
that isn’t offered today.
The features this status lists: what this install has or, in a response from POST /admin/license/validate, what the license would give. Community mode gives core, thumbnails, ai_enrichment, collab and api_access; a license replaces that list with its own. Only sso_ldap, sso_saml and multi_tenant are checked anywhere. The first two add LDAP and SAML to the sign-in options, but neither can sign anyone in; all three gate the admin capabilities that require them.
The license owner’s email address.
The organization the license names.
The license’s ID, as issued.
The seat limit the license states. Left out when it sets none. Nothing enforces it today.
The number of days the license gives for counting active seats. Nothing uses it today.
The asset limit the license states. Left out when it sets none. Nothing enforces it today.
The license isn’t valid before this time.
The license stops being valid after this time.
When the license was issued.
Whole days left until exp, rounded down, as of when the license
was last checked. 0 in community mode.
Why the last check failed, when it did: the file couldn’t be read, failed verification or didn’t match the organization key. The server is then in community mode. If a license path is set but there’s no file at it, this reports the missing file once the server has been up for a day.
The issuer the license names. Verification accepts only
lic.artist-alley.org.
Where the server reads the license file:
/etc/artist-alley/license.lic unless AA_LICENSE_PATH sets
another. May be left out in community mode.
True when the license is tied to an organization key: it works only
if this server holds the matching org.key file.
True when there’s no organization key to match or this server’s
org.key matches it. A license that doesn’t match isn’t loaded: the
server stays in community mode and org_binding_error says why.
Why the organization key check failed, in the verifier’s own words.
Where the server looks for org.key: /etc/artist-alley/org.key
unless AA_ORG_KEY_PATH sets another.
The license failed a check; code says which.
Why a license failed. Branch on code; message is the verifier’s
own text, for logs and support.
object
Always license validation failed.
Which check failed: bad_envelope (the text couldn’t be parsed),
bad_signature, unknown_publisher_key (signed with a key this
server doesn’t know), wrong_issuer, expired, not_yet_valid,
org_key_missing, org_key_bad_format or org_key_mismatch, and
unknown for anything else. The four chain_ codes are reserved
for plugin licenses and aren’t returned by these endpoints.
Raw verifier error string for diagnostics.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completed