Moonbase

Licensing API Reference

Do you have a specific scenario you need to support or other questions?
Reach out to us through the support channel, or at developers@moonbase.sh.

Authentication

The licensing endpoints documented below are made to be called from the apps you create, with the customer initiating any actions.
Therefore, most of the endpoints are publicly available, only some requiring authentication in the form of JWT tokens.
These JWT tokens can be obtained by authenticating the user through /api/customer/identity/sign-in, and the tokens refreshed by handing them in through /api/customer/identity/refresh.

POST/api/customer/identity/sign-in

Sign in a customer

This endpoint allows you to sign in a customer given a combination of email address and password. The JWT returned contains an access token with a default lifetime of 15 minutes. Refresh tokens can be used to get new access tokens.

Required query parameters

  • Name
    email
    Type
    string
    Description

    The email of the customer.

Required body content

The password of the customer.

Request

POST
/api/customer/identity/sign-in
POST https://demo.moonbase.sh/api/customer/identity/sign-in?email=test@example.com
Content-Type: text/plain

Password1234!

Response

{
    "id": "e891f4b0-6d73-48ed-8fc1-c6b166c5379a",
    "name": "Example User",
    "email": "user@example.com",
    "tenantId": "demo",
    "userType": "Customer",
    "accessToken": "eyJhbGciOiJIUzUxMiIsInR5c...",
    "refreshToken": "MDAxNDhiZGUtMzY1Yi00MTYx..."
}
POST/api/customer/identity/refresh

Refresh a token

This endpoint allows you to exchange a refresh token + access token for a new pair of tokens.

Required query parameters

  • Name
    token
    Type
    string
    Description

    The refresh token you got during the last refresh or sign-in if first time refreshing.

Required body content

The access token belonging to the refresh token.

Request

POST
/api/customer/identity/refresh
POST https://demo.moonbase.sh/api/customer/identity/refresh?token=MDAxNDhiZGUtMzY1Yi00MTYx...
Content-Type: text/plain

eyJhbGciOiJIUzUxMiIsInR5c...

Response

{
    "id": "e891f4b0-6d73-48ed-8fc1-c6b166c5379a",
    "name": "Example User",
    "email": "user@example.com",
    "tenantId": "demo",
    "userType": "Customer",
    "accessToken": "eyJhbGciOiJIUzUxMiIsInR5c...",
    "refreshToken": "MDAxNDhiZGUtMzY1Yi00MTYx..."
}
POST/api/customer/identity/sign-up

Sign up

This endpoint allows you to sign up a new customer on your account. Useful if you require accounts to start trials.

Required body properties

  • Name
    name
    Type
    string
    Description

    Full name of the user.

  • Name
    email
    Type
    string
    Description

    Email address of the user. Will be used as username. Can be changed by the user.

  • Name
    password
    Type
    string
    Description

    The initial password for the user. Must contain lower case characters, uppercase characters, numbers and a symbol.

Optional body properties

  • Name
    address
    Type
    object
    Description

    A billing address for the user. Will be used when purchasing new products.
    Contains the following properties:

    • Name
      countryCode
      Type
      string
      Description

      ISO 3166-1 alpha-2 two-letter country code.

    • Name
      streetAddress1
      Type
      string
      Description

      First line of the regular street address.

    • Name
      streetAddress2
      Type
      string
      Optionality
      optional
      Description

      Second line of the regular street address.

    • Name
      postCode
      Type
      string
      Description

      Postal code of the address.

    • Name
      locality
      Type
      string
      Description

      Locality of the address, only required if no region is given.
      Also known as City.

    • Name
      region
      Type
      string
      Description

      Region of the address, only required if no locality is given.
      Also known as State.

Request

POST
/api/customer/identity/sign-up
POST https://demo.moonbase.sh/api/customer/identity/sign-up
Content-Type: application/json

{
    "name": "Example User",
    "email": "user@example.com",
    "password": "Password1234!",
    "address": {
        "countryCode": "NO",
        "streetAddress1": "Slottsplassen 1",
        "streetAddress2": null,
        "postCode": "0010",
        "region": "Oslo",
        "locality": null
    }
}

Response

{
    "id": "e891f4b0-6d73-48ed-8fc1-c6b166c5379a",
    "name": "Example User",
    "email": "user@example.com",
    "tenantId": "demo",
    "userType": "Customer",
    "accessToken": "eyJhbGciOiJIUzUxMiIsInR5c...",
    "refreshToken": "MDAxNDhiZGUtMzY1Yi00MTYx..."
}

Licensing

License tokens generated by Moonbase are generated as JWT tokens. These tokens are signed with your account's private key, while you ship the public key with your apps. Part of the metadata in these tokens allow you to verify that the token is for the device it's being activated on. If you are using frameworks or languages that don't have easy ways to deserialize and validate JWTs, reach out to us through support to investigate alternatives.

License token claims

  • Name
    id
    Type
    string
    Description

    Identifier of this unique license activation.

  • Name
    exp
    Type
    number
    Nullability
    nullable
    Description

    Expiration date and time for this license token. You should have a check that this time is still in the future when validating the license. Only applicable for licenses that expire.

  • Name
    iat
    Type
    number
    Description

    Date and time at which this token was issued at.

  • Name
    nbf
    Type
    number
    Description

    Date and time at which this token becomes valid. Will always be the same as the iat claim.

  • Name
    u:id
    Type
    string
    Description

    Identifier of the user that owns this license. If the user is anonymous, this ID will be an empty GUID (00000000-0000-0000-0000-000000000000).

  • Name
    u:name
    Type
    string
    Description

    The name of the user that owns this license. If the user is anonymous, this will say anonymous.

  • Name
    u:email
    Type
    string
    Description

    The email of the user that owns this license. If the user is anonymous, this will say anonymous.

  • Name
    l:id
    Type
    string
    Description

    The ID of the license that activated this license token. One license may have multiple tokens active depending on seat configuration of the product.

  • Name
    p:id
    Type
    string
    Description

    The ID of the product this license is for. You should have a check that this is the same as the current product the user is activating.

  • Name
    p:name
    Type
    string
    Description

    The name of the product this license is for.

  • Name
    p:rel
    Type
    string
    Optionality
    optional
    Description

    The current release version of the product. If there is no current release for the product, this claim will not be included.

  • Name
    method
    Type
    enum(Online|Offline)
    Description

    The activation method used for activating this license token. Based on this you can determine if re-validations of the license should take place.

  • Name
    sig
    Type
    string
    Description

    The signature of the device being activated. You should have a check that this signature is the same as the device the user is activating.

  • Name
    ver
    Type
    string
    Description

    ISO-8601 date and time of the last time this license token was validated online. You should have a check that this date is not too old for your given re-validation frequency.

  • Name
    trial
    Type
    boolean
    Description

    Flag for if this license token represents a time-limited trial, or a owned license.

  • Name
    vendor
    Type
    string
    Description

    The name of your account.

License token

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNlZjNlMzdiZTMzOGFjYWJkNWRhMDQxMDUwOTkwMjVjIiwidmVuZG9yIjoiRGVtbyBDby4iLCJ1OmlkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwidTpuYW1lIjoiYW5vbnltb3VzIiwidTplbWFpbCI6ImFub255bW91cyIsImw6aWQiOiJjZWYzZTM3YmUzMzhhY2FiZDVkYTA0MTA1MDk5MDI1YyIsInA6aWQiOiJkZW1vLWFwcCIsInA6bmFtZSI6IkRlbW8gQXBwIiwibWV0aG9kIjoiT25saW5lIiwic2lnIjoieExUSTNWREV5T2pFMk9qQTVMalkxTlRVeU5UTmFJaXdpZEhKcFlXd2lPaUowY25WbElpd2lZWFZrSSIsInZlciI6IjIwMjQtMDEtMjdUMTI6MjU6NTcuNTc4MDkwNloiLCJ0cmlhbCI6InRydWUiLCJhdWQiOiJkZW1vLWFwcCIsImV4cCI6MTcwNzU2Nzk1NywiaXNzIjoiZGVtbyIsImlhdCI6MTcwNjM1ODM1NywibmJmIjoxNzA2MzU4MzU3fQ.cze2gijLNTi9IxcgqpKUMk8Eq90dlG0UOvXVlfAwdeDJ-VCLlK3GIHg23t5BzsQjGBJM0GU6mFV-IXrdIdu8ibFdiEpCIqDS880EoEZfRLyKjzOI2n8heBPNWsdLxGz9z40RxGNOp_jNNf_iSfuOFGf_1evLN1o1BPw5iVlXJzk7TMO0D1kF50sCgF1TagtB_hQoK-ilAu-PWm7i_6CXjj3f9msggNBUcbehlF7nd0GWvM6jm0Aq5qc8iYeENLM8696g2xeKP1cj4WdmLirmOg-EZ-b8uw_VoJr0Nupdcg6qCcTzM5ytyPYWAiIDOhLdBfED5BhBeNWcp8kNFUGXYw

Deserialized token

{
    "id": "cef3e37be338acabd5da04105099025c",
    "vendor": "Demo Co.",
    "u:id": "00000000-0000-0000-0000-000000000000",
    "u:name": "anonymous",
    "u:email": "anonymous",
    "l:id": "cef3e37be338acabd5da04105099025c",
    "p:id": "demo-app",
    "p:name": "Demo App",
    "p:rel": "1.0.0",
    "method": "Online",
    "sig": "xLTI3VDEyOjE2OjA5LjY1NTUyNTNaIiwidHJpYWwiOiJ0cnVlIiwiYXVkI",
    "ver": "2024-01-27T12:25:57.5780906Z",
    "trial": "true",
    "aud": "demo-app",
    "exp": 1707567957,
    "iss": "demo",
    "iat": 1706358357,
    "nbf": 1706358357
}
POST/api/client/trials/{productId}/request

Request a trial license token

This endpoint allows you to request a trial license token for the current device. If you have an authenticated customer, you may attach the access token in the Authorization header to authenticate the call. Will return a HTTP 401: Unauthorized if the product requires account to activate trial and you do not have an authenticated customer.

Required body properties

  • Name
    deviceName
    Type
    string
    Description

    The name of the device being activated. Will be shown in the customer portal in case the customer wants to revoke this license activation.

  • Name
    deviceSignature
    Type
    string
    Description

    A fingerprint of the current device that will not change. Should be used when validating future license tokens, that they have indeed been issued for the current device.

Request

POST
/api/client/trials/{productId}/request
POST https://demo.moonbase.sh/api/client/trials/demo-app/request
Content-Type: application/json

{
    "deviceName": "Example Device Name",
    "deviceSignature": "xLTI3VDEyOjE2OjA5LjY1NTUyNTNaIiwidHJpYWwiOiJ0cnVlIiwiYXVkI"
}

Response

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNlZjNlMzdiZTMzOGFjYWJkNWRhMDQxMDUwOTkwMjVjIiwidmVuZG9yIjoiRGVtbyBDby4iLCJ1OmlkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwidTpuYW1lIjoiYW5vbnltb3VzIiwidTplbWFpbCI6ImFub255bW91cyIsImw6aWQiOiJjZWYzZTM3YmUzMzhhY2FiZDVkYTA0MTA1MDk5MDI1YyIsInA6aWQiOiJkZW1vLWFwcCIsInA6bmFtZSI6IkRlbW8gQXBwIiwibWV0aG9kIjoiT25saW5lIiwic2lnIjoieExUSTNWREV5T2pFMk9qQTVMalkxTlRVeU5UTmFJaXdpZEhKcFlXd2lPaUowY25WbElpd2lZWFZrSSIsInZlciI6IjIwMjQtMDEtMjdUMTI6MjU6NTcuNTc4MDkwNloiLCJ0cmlhbCI6InRydWUiLCJhdWQiOiJkZW1vLWFwcCIsImV4cCI6MTcwNzU2Nzk1NywiaXNzIjoiZGVtbyIsImlhdCI6MTcwNjM1ODM1NywibmJmIjoxNzA2MzU4MzU3fQ.cze2gijLNTi9IxcgqpKUMk8Eq90dlG0UOvXVlfAwdeDJ-VCLlK3GIHg23t5BzsQjGBJM0GU6mFV-IXrdIdu8ibFdiEpCIqDS880EoEZfRLyKjzOI2n8heBPNWsdLxGz9z40RxGNOp_jNNf_iSfuOFGf_1evLN1o1BPw5iVlXJzk7TMO0D1kF50sCgF1TagtB_hQoK-ilAu-PWm7i_6CXjj3f9msggNBUcbehlF7nd0GWvM6jm0Aq5qc8iYeENLM8696g2xeKP1cj4WdmLirmOg-EZ-b8uw_VoJr0Nupdcg6qCcTzM5ytyPYWAiIDOhLdBfED5BhBeNWcp8kNFUGXYw
POST Authenticated/api/client/licenses/{productId}/request

Request a license token

This endpoint allows you to request a license token for the current device. Requires an authenticated customer, and that the customers has free license activations on their account to activate the product.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    Access token for the authenticated customer in your app, in the form of a JWT bearer token.

Required body properties

  • Name
    deviceName
    Type
    string
    Description

    The name of the device being activated. Will be shown in the customer portal in case the customer wants to revoke this license activation.

  • Name
    deviceSignature
    Type
    string
    Description

    A fingerprint of the current device that will not change. Should be used when validating future license tokens, that they have indeed been issued for the current device.

Request

POST
/api/client/licenses/{productId}/request
POST https://demo.moonbase.sh/api/client/licenses/demo-app/request
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...

{
    "deviceName": "Example Device Name",
    "deviceSignature": "xLTI3VDEyOjE2OjA5LjY1NTUyNTNaIiwidHJpYWwiOiJ0cnVlIiwiYXVkI"
}

Response

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM2Mjg0YTkwZDQ3ZGY4MTQ1MzBjMDE1ZjBjY2ZkZGZhIiwidmVuZG9yIjoiRGVtbyBDby4iLCJ1OmlkIjoiYmJkNjNhNmYtMmE0MS00MzJkLTg0YjUtNmRjYmFjMGJmZDIwIiwidTpuYW1lIjoiRXhhbXBsZSBVc2VyIiwidTplbWFpbCI6ImV4YW1wbGVAbW9vbndhdGVyLm5vIiwibDppZCI6ImYzZGEyYzlhLWQ3YTAtNGFhOS1hNGI1LTAwNzg2YWU1ZmM5OCIsInA6aWQiOiJkZW1vLWFwcCIsInA6bmFtZSI6IkRlbW8gQXBwIiwibWV0aG9kIjoiT25saW5lIiwic2lnIjoieExUSTNWREV5T2pFMk9qQTVMalkxTlRVeU5UTmFJaXdpZEhKcFlXd2lPaUowY25WbElpd2lZWFZrSSIsInZlciI6IjIwMjQtMDEtMjdUMTI6NDI6NTguODM0MTUzN1oiLCJ0cmlhbCI6ImZhbHNlIiwiYXVkIjoiZGVtby1hcHAiLCJpc3MiOiJkZW1vIiwiaWF0IjoxNzA2MzU5MzA5LCJuYmYiOjE3MDYzNTkzMDl9.jwmAyg2e22mF3Ds4bLMcyrr6e_lO-lpmwhDQz2X9psrwPBlsf3Od8vGGiVlfXZGJJWsTwZBVGTPHx2NpqtexGaytMXlS23rSc0My-nQXsShao-9hyF4nOPHZWVEvUbZkMzk4hbO4AiYlyw2KKyvYGMWA0jITSJKgs-M4YcUl2wQHm5FeXRZyGbc5CzWV7lq74qMqM_EkYZ2nvq6AXEAJ6c9TsP2AEH2zBhi79EbZwE9HWWGEu55pZi8-GBZdeZ1tZfkKz19rOBnWFP8BvKrkCuJDPR7JdRywsYEsRzqI59QANl5zoRAnP9zOn-_b1QQZnZMPOdohn1WVszbDq43bTw
POST/api/client/licenses/{productId}/validate

Validate a license token

This endpoint allows you to send a license token you have to have it validated. For all Online activated tokens, this should be done regularly to be able to deactivate revoked devices fast. You will receive an updated token in return, with new valid validation timestamps if the license is still active.

Required body content

The license token you wish to validate.

Request

POST
/api/client/licenses/{productId}/validate
POST https://demo.moonbase.sh/api/client/licenses/demo-app/validate
Content-Type: text/plain

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM2Mjg0YTkwZDQ3ZGY4MTQ1MzBjMDE1Z...

Response

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM2Mjg0YTkwZDQ3ZGY4MTQ1MzBjMDE1ZjBjY2ZkZGZhIiwidmVuZG9yIjoiRGVtbyBDby4iLCJ1OmlkIjoiYmJkNjNhNmYtMmE0MS00MzJkLTg0YjUtNmRjYmFjMGJmZDIwIiwidTpuYW1lIjoiRXhhbXBsZSBVc2VyIiwidTplbWFpbCI6ImV4YW1wbGVAbW9vbndhdGVyLm5vIiwibDppZCI6ImYzZGEyYzlhLWQ3YTAtNGFhOS1hNGI1LTAwNzg2YWU1ZmM5OCIsInA6aWQiOiJkZW1vLWFwcCIsInA6bmFtZSI6IkRlbW8gQXBwIiwibWV0aG9kIjoiT25saW5lIiwic2lnIjoieExUSTNWREV5T2pFMk9qQTVMalkxTlRVeU5UTmFJaXdpZEhKcFlXd2lPaUowY25WbElpd2lZWFZrSSIsInZlciI6IjIwMjQtMDEtMjdUMTI6NDI6NTguODM0MTUzN1oiLCJ0cmlhbCI6ImZhbHNlIiwiYXVkIjoiZGVtby1hcHAiLCJpc3MiOiJkZW1vIiwiaWF0IjoxNzA2MzU5MzA5LCJuYmYiOjE3MDYzNTkzMDl9.jwmAyg2e22mF3Ds4bLMcyrr6e_lO-lpmwhDQz2X9psrwPBlsf3Od8vGGiVlfXZGJJWsTwZBVGTPHx2NpqtexGaytMXlS23rSc0My-nQXsShao-9hyF4nOPHZWVEvUbZkMzk4hbO4AiYlyw2KKyvYGMWA0jITSJKgs-M4YcUl2wQHm5FeXRZyGbc5CzWV7lq74qMqM_EkYZ2nvq6AXEAJ6c9TsP2AEH2zBhi79EbZwE9HWWGEu55pZi8-GBZdeZ1tZfkKz19rOBnWFP8BvKrkCuJDPR7JdRywsYEsRzqI59QANl5zoRAnP9zOn-_b1QQZnZMPOdohn1WVszbDq43bTw
POST/api/client/licenses/{productId}/revoke

Revoke a license token

This endpoint allows you to send a license token you have to have it revoked. By doing this, you will effectively free up a seat for the customer, so that they can activate other devices. Offline activated license tokens will not be accepted by this endpoint as they are not intended to be floating licenses.

Required body content

The license token you wish to revoke.

Request

POST
/api/client/licenses/{productId}/revoke
POST https://demo.moonbase.sh/api/client/licenses/demo-app/revoke
Content-Type: text/plain

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM2Mjg0YTkwZDQ3ZGY4MTQ1MzBjMDE1Z...

Browser Activations

A good alternative to the above endpoints where you need to authenticate the customer in your apps is to request browser based activation instead. By requesting an activation, you can open a browser where the customer is in most cases already logged in, where they can choose what to fulfill the request with.

POST/api/client/activations/{productId}/request

Request activation

This endpoint allows you to request a activation for the current device. The returned payload will have two URLs that are relevant:

  • Name
    request
    Type
    uri
    Description

    This URL can be polled to check for the current status of the request. See GET /api/client/activations/{requestId} below.

  • Name
    browser
    Type
    uri
    Description

    This URL should be opened in the browser of the current device so the customer can complete the activation process.

Required body properties

  • Name
    deviceName
    Type
    string
    Description

    The name of the device being activated. Will be shown in the customer portal in case the customer wants to revoke this license activation.

  • Name
    deviceSignature
    Type
    string
    Description

    A fingerprint of the current device that will not change. Should be used when validating future license tokens, that they have indeed been issued for the current device.

Request

POST
/api/client/activations/{productId}/request
POST https://demo.moonbase.sh/api/client/activations/demo-app/request
Content-Type: application/json

{
    "deviceName": "Example Device Name",
    "deviceSignature": "xLTI3VDEyOjE2OjA5LjY1NTUyNTNaIiwidHJpYWwiOiJ0cnVlIiwiYXVkI"
}

Response

{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "request": "https://demo.moonbase.sh/api/client/activations/3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "browser": "https://demo.moonbase.sh/activate/auto?token=3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
GET/api/client/activations/{requestId}

Get request status

This endpoint allows you to check the current status of a activation request. By polling this regularly, you can activate the device as soon as the user fulfills the request in their browser. Be careful to not poll too frequently, to avoid rate limiting restrictions on your account. One request per 5 seconds is considered a safe frequency. Until the customer has fulfilled the request, a HTTP 204: No content will be returned. Once fulfilled, the response will contain a license token ready to be used.

Request

GET
/api/client/activations/{requestId}
GET https://demo.moonbase.sh/api/client/activations/3fa85f64-5717-4562-b3fc-2c963f66afa6

Response

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNlZjNlMzdiZTMzOGFjYWJkNWRhMDQxMDUwOTkwMjVjIiwidmVuZG9yIjoiRGVtbyBDby4iLCJ1OmlkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwidTpuYW1lIjoiYW5vbnltb3VzIiwidTplbWFpbCI6ImFub255bW91cyIsImw6aWQiOiJjZWYzZTM3YmUzMzhhY2FiZDVkYTA0MTA1MDk5MDI1YyIsInA6aWQiOiJkZW1vLWFwcCIsInA6bmFtZSI6IkRlbW8gQXBwIiwibWV0aG9kIjoiT25saW5lIiwic2lnIjoieExUSTNWREV5T2pFMk9qQTVMalkxTlRVeU5UTmFJaXdpZEhKcFlXd2lPaUowY25WbElpd2lZWFZrSSIsInZlciI6IjIwMjQtMDEtMjdUMTI6MjU6NTcuNTc4MDkwNloiLCJ0cmlhbCI6InRydWUiLCJhdWQiOiJkZW1vLWFwcCIsImV4cCI6MTcwNzU2Nzk1NywiaXNzIjoiZGVtbyIsImlhdCI6MTcwNjM1ODM1NywibmJmIjoxNzA2MzU4MzU3fQ.cze2gijLNTi9IxcgqpKUMk8Eq90dlG0UOvXVlfAwdeDJ-VCLlK3GIHg23t5BzsQjGBJM0GU6mFV-IXrdIdu8ibFdiEpCIqDS880EoEZfRLyKjzOI2n8heBPNWsdLxGz9z40RxGNOp_jNNf_iSfuOFGf_1evLN1o1BPw5iVlXJzk7TMO0D1kF50sCgF1TagtB_hQoK-ilAu-PWm7i_6CXjj3f9msggNBUcbehlF7nd0GWvM6jm0Aq5qc8iYeENLM8696g2xeKP1cj4WdmLirmOg-EZ-b8uw_VoJr0Nupdcg6qCcTzM5ytyPYWAiIDOhLdBfED5BhBeNWcp8kNFUGXYw

Was this page helpful?