Skip to content

VENDORS.md

Latest commit

 

History

History
202 lines (143 loc) · 5.76 KB

VENDORS.md

File metadata and controls

202 lines (143 loc) · 5.76 KB
title Vendor licensing

API requests must be made using the ApisCP X.509 provided after establishing a vendor relationship with ApisCP. The ApisCP Root Certificates must be used to validate authenticity. These are bundled in /usr/local/apnscp/resources/apnscp.ca or through the public Yum repository.

Requests are made using REST. All vendor requests are prefixed in the vendor/ namespace.

::: tip API in development This API is still under development. This may change! Please direct all feedback to matt@apisnetworks.com :::

Managing activation codes

POST vendor/code
Adds a new license code that may be converted into a license. Codes, once created, count toward license allowance regardless of redemption status.

See LICENSE.md for upgrading from an activation code within ApisCP. Codes may be activated at install time as well; however, it's advised to install without specifying a code to use a trial license until satisfied with the system configuration. MySQL and PostgreSQL cannot be changed once provisioned.

SAMPLE CODE

curl -i \
	--cacert ./apnscp.ca \
	-E ./license.pem \
	-H "Content-Type: application/json" \
	-X POST
	-d '{"type":"startup"}' \
	https://license.apiscp.com/vendor/code

SAMPLE RESPONSE

{"code":"iifGi10LQpKo6cAk2oNKSMMvgz5t2ZC4qcOHN5W8iyssD85TZzYHKhIxUcCB"}

::: details Above creates 1 Startup license activation without any features, such as network restrictions. This means the license may be used anywhere! :::

::: danger Use network restrictions! Network restrictions limit the license usage on a single machine or subnet. Network restrictions may be set using the features property + net subproperty. In the above payload, the license may be restricted on 64.22.68.1/24 by specifying features.net: 64.22.68.1/24:

-d '{"type":"startup","features":{"net":["64.22.68.1/24"]}}' :::

Codes accept a variety of parameters that influence generation.

Parameter Type
type REQUIRED enum from set ['mini','startup','pro']
common_name string, max length 64 characters
features array

Likewise features may consist of one or more optional license attributes.

Feature parameter Type Description
net array Network CIDR or IP address restrictions. See warning.

::: warning IP restriction usage

IP range must include network gateway. If single IP, then IP listed must be in /24 of gateway. ip route show 0/0 will show primary route on server.

  • 64.22.68.14 is valid if gateway is 64.22.68.1.
  • 64.22.68.14 is not valid if gateway is 64.22.69.1. 64.22.68.1/23 would be used instead.

Rationale Failure to do this would allow one to bind an IP restricted address to server in multi-home environment without ever using it thus satisfying restriction requirement. :::

Removing codes

DELETE vendor/code/ID
Activation codes that have not yet been redeemed may be deleted.

SAMPLE CODE

curl -i \
	--cacert ./apnscp.ca \
	-E ./license.pem \
	-H "Content-Type: application/json" \
	-X DELETE \
	"https://license.apiscp.com/vendor/code/iifGi10LQpKo6cAk2oNKSMMvgz5t2ZC4qcOHN5W8iyssD85TZzYHKhIxUcCB"

Listing codes

GET vendor/code
A list of all codes generated may be retrieved through this endpoint.

curl -i \
	--cacert ./apnscp.ca \
	-E ./license.pem \
	-H "Content-Type: application/json" \
	-X GET \
	"https://license.apiscp.com/vendor/code"

SAMPLE RESPONSE

[{"code":"iifGi10LQpKo6cAk2oNKSMMvgz5t2ZC4qcOHN5W8iyssD85TZzYHKhIxUcCB","available":1,"issued":1591601554,"created_at":1591601554,"common_name":"server123"}]

Listing redemptions by code

GET vendor/code/ID
A list of all codes generated may be retrieved through this endpoint.

curl -i \
	--cacert ./apnscp.ca \
	-E ./license.pem \
	-H "Content-Type: application/json" \
	-X GET \
	"https://license.apiscp.com/vendor/code/iifGi10LQpKo6cAk2oNKSMMvgz5t2ZC4qcOHN5W8iyssD85TZzYHKhIxUcCB"

SAMPLE RESPONSE

[{"id":"1","certificate_id":91,"ip":"192.168.0.147","created_at":1591693179}]

Note: certificate_id is the license ID. id is sequential redemption ID, which is unused in vendor licensing.

Managing licenses

Listing licenses

GET vendor/license

List all redeemed licenses.

SAMPLE REQUEST

curl -i \
	--cacert ./apnscp.ca \
	-E ./license.pem \
	-H "Content-Type: application/json" \
	-X GET \
	"https://license.apiscp.com/vendor/license"

SAMPLE RESPONSE

[{"id":91,"common_name":"server123","ip":"192.168.0.147","expire":1595149179,"created":1591693179}]

Revoking licenses

DELETE vendor/license/ID

SAMPLE CODE

curl -i \
	--cacert ./apnscp.ca \
	-E ./license.pem \
	-H "Content-Type: application/json" \
	-X DELETE \
	"https://license.apiscp.com/vendor/license/91"

SAMPLE RESPONSE

true

A 204 is returned when the request succeeds otherwise a 403 if the license ID is unknown or has already been revoked.

Vendor stats

GET vendor/stats
List license statistics.

SAMPLE REQUEST

curl -i \
	--cacert ./apnscp.ca \
	-E ./license.pem \
	-H "Content-Type: application/json" \
	-X GET \
	"https://license.apiscp.com/vendor/stats"

SAMPLE RESPONSE

[{"type":"startup","total":1,"expired":"0","revoked":"0"}]

"total" reflects all licenses issued. "active" would be determined from total - expired - revoked.