API Reference

Anystack's API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Anystack provides two different API's. The base API is for interacting with your account and manage products, licenses, policies, contacts, and releases. The distribution API provides very specific endpoints which are tailor made for your product platform. For example, an endpoint for auto updating your Electron Builder application.

Authentication

Anystack's API uses API keys to authenticate requests. You can view and manage your API keys from your account settings.

We recommend to create multiple API keys and set granular permissions. Be sure to keep all your API keys secure and do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

Anystack uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a license verification failed, etc.). Codes in the 5xx range indicate an error with Anystack's servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., a license is suspended) include an error code that briefly explains the error reported.

Pagination

All top-level API resources are paginated. These list API responses share a common structure.

Response Format

  • data array

    An array containing the actual response elements, paginated by any request parameters.

  • links array

    An array containing links to navigate between the first, last, previous and next page.

  • meta array

    An array containing more detailed pagination information like current_page, from, last_page, links, path, per_page, to and total.

Products

All top-level API resources are paginated. These list API responses share a common structure.

Product objects allow you to manage your products that are associated with your account. The API allows you to create, delete, and update your products. You can retrieve individual products as well as a list of all your products.

The product object

Attributes

  • id string

    Unique identifier for the object.

  • name string

    The name of the product.

  • slug string

    Unique text identifier.

  • url string

    The url to the product website.

  • logo string

    The url to the product logo.

  • type string

    The product type, e.g. electron or php.

  • updater string

    The type of updater the product is using, e.g. electron-builder, electron-native, and composer.

  • distribution boolean

    If this product is distributed via Anystack.

  • public_distribution_page boolean

    If the public download page (hosted by Anystack) is enabled.

  • distribution_requires_license boolean

    If a license is required in order to download given product.

  • created_at string (ISO8601)

    When the product was created.

  • updated_at string (ISO8601)

    When the product was last updated.

  • links array

    Links to associated product resources.

Create a product

Parameters

  • name required

    The name of the product.

  • slug required

    Unique text identifier.

  • url optional

    The url to the product website.

  • type required

    The product type, e.g. electron or php.

  • updater required

    The type of updater the product is using, e.g. electron-builder, electron-native, and composer.

  • distribution optional

    If this product is distributed via Anystack.

  • public_distribution_page optional

    If the public download page (hosted by Anystack) is enabled.

  • distribution_requires_license optional

    If a license is required in order to download given product.

Returns

Returns the product object.

Retrieve a product

Retrieves the details of an existing product. You need only supply the unique product identifier that was returned upon product creation.

Parameters

No parameters.

Returns

Returns a product object if a valid identifier was provided.

Update a product

Updates the specified product by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

This request accepts mostly the same arguments as the product creation call. Product type and updater cannot be changed at this time.

Parameters

  • name optional

    The name of the product.

  • url optional

    The url to the product website.

  • distribution optional

    If this product is distributed via Anystack.

  • public_distribution_page optional

    If the public download page (hosted by Anystack) is enabled.

  • distribution_requires_license optional

    If a license is required in order to download given product.

Returns

Returns the product object if the update succeeded. Throws an error if update parameters are invalid (e.g. specifying an empty product name).

Delete a product

Deletes a product. Associated resources like releases, policies, and licenses will become unavailable as well.

Parameters

No parameters.

Returns

Returns 200 - OK status code on success. If the product ID does not exist, this call throws an error.

List all products

Returns a list of your products. The products are returned sorted by creation date, with the most recent products appearing first.

Parameters

  • page optional

    The page number

Returns

A associative array with a data property that contains an array of up to 20 products. Each entry in the array is a separate product object. If no more products are available, the resulting array will be empty.

Releases

This is an object representing a release hosted on Anystack's servers. A release contains one or more assets. A release is automatically created if you publish a release on Github or you can manually import a existing release from the release dashboard.

The release object

Attributes

  • id string

    Unique identifier for the object.

  • tag string

    Unique release version identifier for the release.

  • draft boolean

    If set to true the release is not available publicly.

  • description string

    A description about the release.

  • prerelease boolean

    If the release is stable or for early adaptors, beta users, etc.

  • created_at string (ISO8601)

    When the release was created.

  • updated_at string (ISO8601)

    When the release was last updated.

  • published_at string (ISO8601)

    When the release was published.

  • links array

    Links to associated release resources.

Retrieve a release

Retrieves the details of an existing release. You need only supply the unique release identifier.

Parameters

No parameters.

Returns

Returns a release object if a valid identifier was provided.

Update a release

Updates the specified release by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

  • tag optional

    Unique release version identifier for the release. Changing the tag of a previously published release may have undesirable side effects. We recommend to create a new release.

  • draft optional

    If set to true the release is not available publicly. If set to false the release will be published.

  • description optional

    A description about the release.

  • prerelease optional

    If the release is stable or for early adaptors, beta users, etc.

  • links array

    Links to associated release resources.

Returns

Returns the release object if the update succeeded. Throws an error if update parameters are invalid (e.g. specifying an invalid tag).

Delete a release

Deletes a release. Associated resources like assets will become unavailable as well.

Parameters

No parameters.

Returns

Returns 200 - OK status code on success. If the release ID does not exist, this call throws an error.

List all releases

Returns a list of your product releases. The releases are returned sorted by tag, with the most recent tag appearing first. See Semantic versioning for more information.

Parameters

  • page optional

    The page number

Returns

A associative array with a data property that contains an array of up to 20 releases. Each entry in the array is a separate release object. If no more releases are available, the resulting array will be empty.

Assets

This is an object representing a asset hosted on Anystack's servers. Each release consists out of one or more assets.

The asset object

Attributes

  • id string

    Unique identifier for the object.

  • size int

    The asset file size.

  • content_type string

    The asset content type.

  • filename string

    The asset filename.

  • url string

    The asset download url. Product distribution settings apply, e.g. a license key may be required to download given asset.

  • platform string

    For which platform the asset is, e.g. darwin, win32 or linux.

  • platform_arch string

    For which platform architecture type the asset is, e.g. x64 or arm64.

  • checksum string

    The asset checksum.

  • created_at string (ISO8601)

    When the asset was created.

  • updated_at string (ISO8601)

    When the asset was last updated.

  • links array

    Links to associated asset resources.

Retrieve an asset

Retrieves the details of an existing asset. You need only supply the unique asset identifier.

Parameters

No parameters.

Returns

Returns a asset object if a valid identifier was provided.

Delete an asset

Deletes an asset.

Parameters

No parameters.

Returns

Returns 200 - OK status code on success. If the asset ID does not exist, this call throws an error.

List all assets

Returns a list of your release assets. The assets are returned sorted by filename.

Parameters

  • page optional

    The page number

Returns

A associative array with a data property that contains an array of up to 20 assets. Each entry in the array is a asset release object. If no more assets are available, the resulting array will be empty.

Policies

Policies are our way of defining different type of licenses, for example, you might offer yearly software licenses or maybe set a usage limit.

Another example, an everyday use case is to have yearly software licenses that once they expire will still work, but you cannot get any more product updates. This is something you can achieve with policies.

The policy object

Attributes

  • id string

    Unique identifier for the object.

  • name string

    The name of the policy.

  • duration integer

    After how many seconds a license expires.

  • max_usage integer

    The maximum amount of license activations, e.g. websites, devices, etc.

  • requires_fingerprint string

    If the license requires a unique fingerprint, e.g. domain, ip, etc.

  • release_constraint string

    License release constraint, e.g. only allow access to one major version like v1.

  • expire_consequence string
    • revoke_access (default): upon expiration, revoke all access.
    • restrict_access: upon expiration, restricts access to releases published before the license expiry date.
  • created_at string (ISO8601)

    When the policy was created.

  • updated_at string (ISO8601)

    When the policy was last updated.

  • links array

    Links to associated policy resources.

Create a policy

Parameters

  • name required

    The name of the policy.

  • duration optional

    After how many seconds a license expires.

  • max_usage optional

    The maximum amount of license activations, e.g. websites, devices, etc.

  • requires_fingerprint optional

    If the license requires a unique fingerprint, e.g. domain, ip, etc.

  • release_constraint optional

    License release constraint, e.g. only allow access to one major version like v1.

  • expire_consequence optional
    • revoke_access (default): upon expiration, revoke all access.
    • restrict_access: upon expiration, restricts access to releases published before the license expiry date.
  • created_at string (ISO8601)

    When the policy was created.

  • updated_at string (ISO8601)

    When the policy was last updated.

  • links array

    Links to associated policy resources.

Returns

Returns the policy object.

Retrieve a policy

Retrieves the details of an existing policy. You need only supply the unique policy identifier that was returned upon policy creation.

Parameters

No parameters.

Returns

Returns a policy object if a valid identifier was provided.

Update a policy

Updates the specified policy by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

  • name optional

    The name of the policy.

  • duration optional

    After how many seconds a license expires.

  • max_usage optional

    The maximum amount of license activations, e.g. websites, devices, etc.

  • requires_fingerprint optional

    If the license requires a unique fingerprint, e.g. domain, ip, etc.

  • release_constraint optional

    License release constraint, e.g. only allow access to one major version like v1.

  • expire_consequence optional
    • revoke_access (default): upon expiration, revoke all access.
    • restrict_access: upon expiration, restricts access to releases published before the license expiry date.
  • links array

    Links to associated policy resources.

Returns

Returns the policy object if the update succeeded. Throws an error if update parameters are invalid (e.g. specifying an empty policy name).

Delete a policy

Deletes a policy. A policy cannot be deleted if it has any licenses.

Parameters

No parameters.

Returns

Returns 200 - OK status code on success. If the policy ID does not exist, this call throws an error.

List all policies

Returns a list of your policies. The policies are returned sorted by creation date, with the most recent policies appearing first.

Parameters

  • page optional

    The page number

Returns

A associative array with a data property that contains an array of up to 20 policies. Each entry in the array is a separate policy object. If no more policies are available, the resulting array will be empty.

Contacts

A contacts represents an entity who can be associated with one or multiple licenses.

The contact object

Attributes

  • id string

    Unique identifier for the object.

  • first_name string

    The first name of the contact.

  • last_name string

    The last name of the contact.

  • email string

    The email of the contact.

  • created_at string (ISO8601)

    When the contact was created.

  • updated_at string (ISO8601)

    When the contact was last updated.

  • links array

    Links to associated contact resources.

Create a contact

Parameters

  • first_name optional

    The first name of the contact.

  • last_name optional

    The last name of the contact.

  • email required

    The email of the contact.

Returns

Returns the contact object.

Retrieve a contact

Retrieves the details of an existing contact. You need only supply the unique contact identifier that was returned upon contact creation.

Parameters

No parameters.

Returns

Returns a contact object if a valid identifier was provided.

Update a contact

Updates the specified contact by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

This request accepts mostly the same arguments as the contact creation call.

You cannot update contacts that have been created automatically during checkout. These contacts can manage their details via their account dashboard.

Parameters

  • first_name optional

    The first name of the contact.

  • last_name optional

    The last name of the contact.

  • email optional

    The email of the contact.

Returns

Returns the contact object if the update succeeded. Throws an error if update parameters are invalid (e.g. specifying an invalid email).

Delete a contact

Deletes a contact.

You cannot delete contacts that have been created automatically during checkout. These contacts can manage their details via their account dashboard.

Parameters

No parameters.

Returns

Returns 200 - OK status code on success. If the contact ID does not exist, this call throws an error.

List all contacts

Returns a list of your contacts. The contacts are returned sorted by creation date, with the most recent contacts appearing first.

Parameters

  • page optional

    The page number

Returns

A associative array with a data property that contains an array of up to 20 contacts. Each entry in the array is a separate contact object. If no more contacts are available, the resulting array will be empty.

Create a contact session

If you don't want to implement the required logic for your users to manage their licenses, you can use Anystack's contact sessions API. Contact sessions provide you with a similar experience to Stripe checkout.

Provide Anystack with your contact and product identifier and Anystack will return a unique URL to the customer's license portal to manage their licenses.

Parameters

  • product_id required

    Unique identifier for the product.

  • contact_id required

    Unique identifier for the contact.

  • return_url required

    Where should users return to if they exit their session.

  • permissions optional

    Array with permissions or leave empty if users are only allowed to view their licenses.

    • activation:create: Allow users to activate their license.
    • activation:delete: Allow users to revoke existing activations (e.g. remove a device or domain).
  • activation_fields optional

    Array of fields which will be required to activate a license (besides fingerprint). These fields will also be visible for existing license activations.

    • name
    • hostname
    • platform
    • ip
  • fingerprint_label optional

    The term fingerprint might be unclear for your users, you might use a domain name, device identifier or any other unique identifier. You can set your custom label with this property.

Returns

Returns the contact session object.

Attributes

  • id string

    Unique identifier for the object.

  • product_id string

    Unique identifier for the product attached to this session.

  • return_url string

    The URL where users return to if they exit their session.

  • session_url string

    The URL to redirect your user to so they can manage their licenses. Please note that a session url can only be accessed once.

  • permissions array

    Array with permissions but may be left empty if users are only allowed to view their licenses.

  • activation_fields array

    Array of fields which will be required to activate a license. May be left empty if only the fingerprint is relevant.

  • fingerprint_label string

    Custom label to use instead of the word "Fingerprint".

  • expires_at string (ISO8601)

    Timestamp when the session expires.

Licenses

A license is used to authorize a user by making sure the provided license key is valid. You can store multiple licenses on a contact.

The license object

Attributes

  • id string

    Unique identifier for the object.

  • policy_id string

    The policy that applies to the license object.

  • contact_id string|null

    Contact who is assigned to the license object.

  • licensee_id string|null

    This field is deprecated and will be removed.

  • name string

    The name of the license.

  • key string

    The license key.

  • activations integer

    How many time the license has been activated.

  • max_activations integer

    The maximum amount of activations allowed by the license policy.

  • suspended boolean

    If the license has been suspended or not.

  • expires_at string (ISO8601)

    When the license will expire.

  • created_at string (ISO8601)

    When the license was created.

  • updated_at string (ISO8601)

    When the license was last updated.

  • links array

    Links to associated license resources.

Create a license

Parameters

  • policy_id required

    Unique identifier for the license policy.

  • contact_id optional

    Unique identifier for the contact to associate with this license.

  • name optional

    The name of the license.

  • key optional

    The license key. When omitted, a license key will be generated for you automatically.

  • suspended optional

    If the license is suspended or not.

  • expires_at optional

    When the license will expire. When omitted, the expire date will be set based on the license policy.

Returns

Returns the license object.

Retrieve a license

Retrieves the details of an existing license. You need only supply the unique license identifier that was returned upon license creation.

Parameters

No parameters.

Returns

Returns a license object if a valid identifier was provided.

Activate a license

This endpoint allows you to activate licenses. When a license is activated, a activation is created. The fingerprint has to be unique, when you try to activate a license twice with the same fingerprint the request will fail. You can store additional data like hostname, ip or platform if you would like to track additional information about the activation.

Parameters

  • key required

    The license key.

  • fingerprint required

    Unique identifier for this activation, e.g. device identifier

  • hostname optional

    Hostname you want to associate with this activation.

  • ip optional

    The IP address you want to associate with this activation.

  • platform optional

    The platform you want to associate with this activation.

Returns

Returns the activation object.

Error codes

FINGERPRINT_MISSING
A required fingerprint for this license is missing.
SUSPENDED
Given license has been suspended.
EXPIRED
Given license has expired.
NOT_FOUND
Given license could not be found.
FINGERPRINT_ALREADY_EXISTS
Given license fingerprint already exists.

Validate a license

This endpoint allows you to verify if a license is valid without triggering an activation.

Parameters

  • key required

    The license key.

  • scope optional

    Apply additional scope to license validation.

    • fingerprint optional

      Unique identifier for this activation, e.g. device identifier

    • release optional

      Apply release scope to the license validation.

      • tag optional

        Unique release version identifier for the release.

    • contact optional

      Apply contact scope to the license validation.

      • email optional

        Verify if contact email matches with the license.

Returns

Returns the license object with additional meta data if the provided license key is valid. If the key or fingerprint an additional status code is returned in the meta data:

Error codes

FINGERPRINT_MISSING
A required fingerprint for this license is missing.
SUSPENDED
Given license has been suspended.
EXPIRED
Given license has expired.
RESTRICTED
Given license has expired but still has access to the version that was available upon the expire date.
FINGERPRINT_INVALID
Given license fingerprint does not exist or is invalid.

Update a license

Updates the specified license by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

  • policy_id optional

    Unique identifier for the license policy. Changing the license policy may have undesirable side effects.

  • contact_id optional

    Unique identifier for the contact to associate with this license.

  • name optional

    The name of the license.

  • suspended optional

    If the license is suspended or not.

  • expires_at optional

    When the license will expire. When omitted, the expire date will be set based on the license policy.

Returns

Returns the license object if the update succeeded. Throws an error if update parameters are invalid (e.g. specifying an invalid policy id).

Delete a license

Deletes a license.

Parameters

No parameters.

Returns

Returns 200 - OK status code on success. If the license ID does not exist, this call throws an error.

Renew a license

Renew given license with the duration of the associated policy. If the license has not expired yet, the associated policy duration will be added to the existing expiration date.

Returns

Returns the license object if the update succeeded. Throws an error if update parameters are invalid.

List all licenses

Returns a list of your licenses. The licenses are returned sorted by creation date, with the most recent licenses appearing first.

Parameters

  • page optional

    The page number

Returns

A associative array with a data property that contains an array of up to 20 licenses. Each entry in the array is a separate license object. If no more licenses are available, the resulting array will be empty.

Activations

When a license is activated an activation record is created. By default, a license can be activated indefinitely, you can use the license policy to enforce an activation limit.

The activation object

Attributes

  • id string

    Unique identifier for the object.

  • license_id string

    Unique identifier of the associated license.

  • name string

    A name for the activation.

  • fingerprint string

    A unique fingerprint.

  • hostname string

    The hostname to associate with this activation.

  • ip string

    The ip to associate with this activation.

  • platform string

    The platform to associate with this activation.

  • created_at string (ISO8601)

    When the activation was created.

  • updated_at string (ISO8601)

    When the activation was last updated.

  • links array

    Links to associated activation resources.

Retrieve an activation

Retrieves the details of an existing activation. You need only supply the unique activation identifier that was returned upon license activation.

Parameters

No parameters.

Returns

Returns a activation object if a valid identifier was provided.

Update an activation

Updates the specified activation by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

  • name optional

    A name for the activation.

  • fingerprint optional

    A unique fingerprint.

  • hostname optional

    The hostname to associate with this activation.

  • ip optional

    The ip to associate with this activation.

  • platform optional

    The platform to associate with this activation.

Returns

Returns the activation object if the update succeeded. Throws an error if update parameters are invalid (e.g. specifying an invalid ip).

Delete an activation

Deletes a activation.

Parameters

No parameters.

Returns

Returns 200 - OK status code on success. If the activation ID does not exist, this call throws an error.

List all activations

Returns a list of your activations. The activations are returned sorted by creation date, with the most recent activations appearing first.

Parameters

  • page optional

    The page number

Returns

A associative array with a data property that contains an array of up to 20 activations. Each entry in the array is a separate activation object. If no more activations are available, the resulting array will be empty.

Examples

The following section will include examples to help you get started. More examples are added over time. Don't hesitate to reach out to [email protected] if you have any questions.

The API Playground

You can use the API Playground to see examples on how you can use Anystack's API. For example, experience the API flow to follow on how to create and activate a license once someone purchases your product.

Requirements

  • To use the API playground you will need to enter one of your API tokens.
  • The API token must have the following permissions: activation:view, license:activate, license:create, contact:create, policy:view, and product:view
  • You need to have at least one product with one license policy.

Ready to get started? Click here to open the API Playground.