Skip to content

Install a license

POST
/admin/license/upload

Checks a license the same way POST /admin/license/validate does and, if it passes, writes it to the license file and starts using it. The response is the new status.

If the license fails the checks made before writing, you get a 400 and nothing is written. Otherwise the server overwrites the file in place; it isn’t swapped in atomically. A failed write gets a 500 and can leave the old file cut short. A new file is created with mode 0600; an existing file keeps its mode.

After writing, the server reads the file back, checks it again and switches to it: the new feature list applies straight away, without a restart. If that second check fails, the new file stays on disk, the server falls back to community mode and you get a 400 or 500 instead of the new status.

The file is /etc/artist-alley/license.lic unless AA_LICENSE_PATH sets another path. Installing isn’t recorded in the audit log. You need system.admin.

The license to check or install: the full text of the .lic file, exactly as issued.

object
license_text
required

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.

string
>= 32 characters <= 65536 characters

Installed and in use. The body is the new status.

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
loaded
required

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.

boolean
tier
required

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.

string
features
required

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.

Array<string>
owner

The license owner’s email address.

string
org

The organization the license names.

string
lid

The license’s ID, as issued.

string
seats

The seat limit the license states. Left out when it sets none. Nothing enforces it today.

integer format: int64
nullable
seat_window_days

The number of days the license gives for counting active seats. Nothing uses it today.

integer
asset_cap

The asset limit the license states. Left out when it sets none. Nothing enforces it today.

integer format: int64
nullable
nbf

The license isn’t valid before this time.

string format: date-time
exp

The license stops being valid after this time.

string format: date-time
iat

When the license was issued.

string format: date-time
days_until_expiry
required

Whole days left until exp, rounded down, as of when the license was last checked. 0 in community mode.

integer
last_error

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.

string
iss

The issuer the license names. Verification accepts only lic.artist-alley.org.

string
path

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.

string
org_binding_required
required

True when the license is tied to an organization key: it works only if this server holds the matching org.key file.

boolean
org_bound
required

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.

boolean
org_binding_error

Why the organization key check failed, in the verifier’s own words.

string
org_key_path

Where the server looks for org.key: /etc/artist-alley/org.key unless AA_ORG_KEY_PATH sets another.

string

The license failed a check; code says which. If it failed before the write, nothing changed; if it failed the check after the write, the new file is on disk and the server is in community mode.

Why a license failed. Branch on code; message is the verifier’s own text, for logs and support.

object
error
required

Always license validation failed.

string
code
required

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.

string
message
required

Raw verifier error string for diagnostics.

string

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

The license path is set to an empty value, so there’s nowhere to write. Set AA_LICENSE_PATH to a path and restart.

object
error
required

Human-readable error summary

string
Example
the request could not be completed

The license passed its checks but the server couldn’t write it or read it back, for example because the directory is missing or not writable. The server doesn’t create directories. An old file that was being overwritten may now be incomplete.

object
error
required

Human-readable error summary

string
Example
the request could not be completed