Moonbase
Docs

Core API Reference

The Moonbase Core API has endpoints where you can manage your Moonbase account using API keys from other systems. It's the ideal set of endpoints to use when building custom integrations or migrating a lot of data to Moonbase.

When calling endpoints, be sure to use the full URL including your Moonbase account ID. Examples on this page assumes an account ID of demo, and so the base URL for all endpoints will be https://demo.moonbase.sh/api/.

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

All endpoints that are part of this Core API require an API key on requests. API keys can be created in your Moonbase account settings, and should be included in a header called Api-Key. For example:

curl -X 'GET' https://demo.moonbase.sh/api/products \
    -H 'Api-Key: mb_bbdac119b64649f6937e...'

Pagination

For endpoints that query a list of resources, we have pagination in place to make sure you can iterate through large amounts of data easily. When you receive paginated responses, they always come wrapped in the same response wrapper:

  • Name
    items
    Type
    array
    Description

    This array contains objects with the resources requested.

  • Name
    hasMore
    Type
    boolean
    Description

    Flag to indicate whether there are more results to be retrieved.

  • Name
    next
    Type
    string
    Nullability
    nullable
    Description

    The path to call to get the next page of results.

Pagination example

{
    "items": [
        {
            ...
        }
    ],
    "hasMore": true,
    "next": "/api/customers?paginationToken=..."
}

Customers

Use customer endpoints to manage your customer accounts and get insights into who are buying your products. The customer object will contain the following fields:

  • Name
    id
    Type
    string
    Description

    The Moonbase ID of the customer.

  • Name
    name
    Type
    string
    Description

    The full name of the customer.

  • Name
    businessName
    Type
    string
    Nullability
    nullable
    Description

    If the customer is a business, this holds the business name.

  • Name
    taxId
    Type
    string
    Nullability
    nullable
    Description

    If the customer is a business, this holds the tax ID if given.

  • Name
    email
    Type
    string
    Description

    Current email address of the customer.

  • Name
    emailConfirmed
    Type
    boolean
    Description

    Flag for if the current email address has ever been confirmed.

  • Name
    hasPassword
    Type
    boolean
    Description

    Flag for if the customer has created a password yet.

  • Name
    isDeleted
    Type
    boolean
    Description

    Flag for if the this customer account has been deleted.

  • Name
    ownedProducts
    Type
    array
    Description

    List of product IDs that this customer owns.

  • Name
    subscribedProducts
    Type
    array
    Description

    List of product IDs that this customer is currently subscribed to.

  • Name
    address
    Type
    object
    Nullability
    nullable
    Description

    Billing address for the customer if stored. 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.

  • Name
    communicationPreferences
    Type
    object
    Description

    Contains specific communication opt-ins given by the customer:

    • Name
      newsletterOptIn
      Type
      boolean
      Description

      Flag for if the customer wants to receive newsletters.

Customer example

{
    "id": "49b8da10-2d72-4bdf-bf9c-47e56c184bfa",
    "name": "Tobias",
    "businessName": null,
    "taxId": null,
    "email": "tobias@moonbase.sh",
    "emailConfirmed": true,
    "hasPassword": true,
    "isDeleted": false,
    "ownedProducts": [
        "example-app"
    ],
    "subscribedProducts": [],
    "address": null,
    "communicationPreferences": {
        "newsletterOptIn": true
    }
}
GET Authenticated/api/customers

Get customers

Use this endpoint to fetch all customers page by page. For more details on how pagination works, see pagination.

Optional query parameters

  • Name
    pageSize
    Type
    number
    Optionality
    optional
    Description

    Adjust the size of each page returned.

Request

POST
/api/customers
GET https://demo.moonbase.sh/api/customers
Api-Key: mb_bbdac119b64649f6937e...

Response

{
    "items": [
        {
            "id": "49b8da10-2d72-4bdf-bf9c-47e56c184bfa",
            "name": "Tobias",
            ...
        }
    ],
    "hasMore": false,
    "next": null
}
GET Authenticated/api/customers/{id|email}

Get customer by ID or email

Use this endpoint to look up a customer by their ID or email address.

Request

POST
/api/customers/{id|email}
GET https://demo.moonbase.sh/api/customers/tobias@moonbase.sh
Api-Key: mb_bbdac119b64649f6937e...

Response

{
    "id": "49b8da10-2d72-4bdf-bf9c-47e56c184bfa",
    "name": "Tobias",
    ...
}
POST Authenticated/api/customers/import

Import customer

Importing a customer creates them a user account. It will not send any emails to the customer, and they will be able to reset their password using the normal reset password flow on your website or the hosted customer portal. You can also supply their password if you already have it, or can generate a secure one.

In case a customer account with the given email already exists, you will receive a 409: Conflict response, where you can access the customer ID using the instance property of the error object.

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.

Optional body properties

  • Name
    password
    Type
    string
    Optionality
    optional
    Description

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

  • Name
    address
    Type
    object
    Optionality
    optional
    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/customers/import
POST https://demo.moonbase.sh/api/customers/import
Api-Key: mb_bbdac119b64649f6937e...
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": "49b8da10-2d72-4bdf-bf9c-47e56c184bfa",
    "name": "Example User",
    ...
}
PATCH Authenticated/api/customers/{id}

Update customer

This endpoint can be used to partially update customer accounts, with every property being optional.

Optional body properties

  • Name
    name
    Type
    string
    Optionality
    optional
    Description

    Full name of the user.

  • Name
    email
    Type
    string
    Optionality
    optional
    Description

    Email address of the user. Will be used as username. Can be changed by the user. Changing this will not send an email to the customer, and they will immediately be able to log in using the new address.

  • Name
    communicationPreferences
    Type
    object
    Optionality
    optional
    Description

    If you have collected updated communication opt-ins, you can update those using this object:

    • Name
      newsletterOptIn
      Type
      boolean
      Description

      Flag for if this customer has opted in to receive newsletters.

Request

PATCH
/api/customers/{id}
PATCH https://demo.moonbase.sh/api/customers/49b8da10-2d72-4bdf-bf9c-47e56c184bfa
Api-Key: mb_bbdac119b64649f6937e...
Content-Type: application/json

{
    "name": "Example User",
    "communicationPreferences": {
        "newsletterOptIn": true
    }
}

Response

{
    "id": "49b8da10-2d72-4bdf-bf9c-47e56c184bfa",
    "name": "Example User",
    ...
}
DELETE Authenticated/api/customers/{id}

Delete customer

Use this to delete customers from your Moonbase account. They will lose access to all products, and their user will be stripped of all personal information. Deleting customers will not affect historical sales, as we are required to store billing details for financial compliancy.

Request

DELETE
/api/customers/{id}
DELETE https://demo.moonbase.sh/api/customers/49b8da10-2d72-4bdf-bf9c-47e56c184bfa
Api-Key: mb_bbdac119b64649f6937e...

Response

{
    "id": "49b8da10-2d72-4bdf-bf9c-47e56c184bfa",
    "name": "Example User",
    ...
}

Licenses

License endpoints let you manage the full life cycle of licenses, including individual activations. If you need to connect your own licensing system with Moonbase licenses, these endpoints should suffice. The license object contains the following:

  • Name
    id
    Type
    string
    Description

    The Moonbase ID of the license.

  • Name
    ownerId
    Type
    string
    Description

    The Moonbase ID of the customer that owns this license.

  • Name
    productId
    Type
    string
    Description

    The Moonbase ID of the product that this license is for.

  • Name
    status
    Type
    enum(Active|Revoked|Expired)
    Description

    Current status of the license:

    • Active: The license can be used by the customer
    • Revoked: The license has been revoked by the merchant
    • Expired: The subscription for the license has expired
  • Name
    activeNumberOfActivations
    Type
    number
    Description

    Number of devices currently activated on this license.

  • Name
    maxNumberOfActivations
    Type
    number
    Description

    Max number of devices allowed to activate this license.

  • Name
    offlineActivationsAllowed
    Type
    boolean
    Description

    Flag for if offline activations are allowed for this license.

License example

{
    "id": "32016591-73c5-4956-938c-e34366599bc7",
    "ownerId": "49b8da10-2d72-4bdf-bf9c-47e56c184bfa",
    "productId": "example-app",
    "status": "Active",
    "activeNumberOfActivations": 0,
    "maxNumberOfActivations": 1,
    "offlineActivationsAllowed": false
}
GET Authenticated/api/licenses/{id}

Get license

Use this endpoint to look up a license by its ID.

Request

POST
/api/licenses/{id}
GET https://demo.moonbase.sh/api/licenses/32016591-73c5-4956-938c-e34366599bc7
Api-Key: mb_bbdac119b64649f6937e...

Response

{
    "id": "32016591-73c5-4956-938c-e34366599bc7",
    "ownerId": "49b8da10-2d72-4bdf-bf9c-47e56c184bfa",
    "productId": "example-app",
    "status": "Active",
    ...
}
POST Authenticated/api/licenses/import

Import license

Importing a license is almost the same as provisioning it through the Moonbase app, with the exception of no communication to the customer being done. The license will be available on their account immediately, and can be used to import a large amount of licenses.

Required body properties

  • Name
    ownerId
    Type
    string
    Description

    Moonbase ID of the customer that should receive this license.

  • Name
    productId
    Type
    string
    Description

    Moonbase ID of the product that this license is for.

Optional body properties

  • Name
    maxNumberOfActivations
    Type
    number
    Optionality
    optional
    Description

    Max number of devices allowed to activate this license. If omitted, Moonbase will use the currently configured value from the product.

  • Name
    offlineActivationsAllowed
    Type
    boolean
    Optionality
    optional
    Description

    Flag for if offline activations are allowed for this license. If omitted, Moonbase will use the currently configured value from the product.

  • Name
    activations
    Type
    array
    Optionality
    optional
    Description

    If you know devices that have already activated this license, you can also import them. It's important that the device signature will be the same so that license activation finds the correct seat to activate. Each activation contains the following properties:

    • Name
      deviceName
      Type
      string
      Description

      User-friendly name of the device.

    • Name
      deviceSignature
      Type
      string
      Description

      Fingerprint of the device generated by the licensing SDK.

    • Name
      activationMethod
      Type
      enum(Online|Offline)
      Description

      Flag for if this activation has been activated as an online or offline device.

    • Name
      lastValidation
      Type
      datetime
      Description

      ISO-8601 date and time for when the device was last validated.

Request

POST
/api/licenses/import
POST https://demo.moonbase.sh/api/licenses/import
Api-Key: mb_bbdac119b64649f6937e...
Content-Type: application/json

{
    "ownerId": "49b8da10-2d72-4bdf-bf9c-47e56c184bfa",
    "productId": "example-app"
}

Response

{
    "id": "32016591-73c5-4956-938c-e34366599bc7",
    "ownerId": "49b8da10-2d72-4bdf-bf9c-47e56c184bfa",
    "productId": "example-app",
    "status": "Active",
    ...
}

Was this page helpful?