Apps

Key Concepts

Architecture

Apps are separate applications that use GraphQL to talk to a Nautical server and that can receive webhooks with event notifications from Nautical.

Authentication

Unlike regular users, apps use a bearer token. The token is assigned at App installation time and needs to be stored in a secure manner.

The authorization header for apps has the following format:

Authorization: Bearer <app-token>

Permissions

When you create a custom app you must assign its permissions:

Name	Description
MANAGE_STAFF	Access to staff users data
MANAGE_APPS	Manage apps
MANAGE_USERS	Access to customers data
MANAGE_DISCOUNTS	Manage discounts
MANAGE_PLUGINS	Manage plugins
MANAGE_GIFT_CARD	Manage gift cards
MANAGE_MENUS	Manage the structure of menus
MANAGE_ORDERS	Access to orders data
MANAGE_PAGES	Manage pages
MANAGE_PRODUCTS	Manage products
MANAGE_PRODUCT_TYPES_AND_ATTRIBUTES	Manage product types and attributes
MANAGE_SHIPPING	Manage shipping
MANAGE_SETTINGS	Manage shop settings
MANAGE_TRANSLATIONS	Manage translations
MANAGE_CHECKOUTS	Manage checkout

Webhooks

Webhooks can be used to receive data from Nautical when particular events happen. For more information, see Webhooks.

Add an App Using the API

Third-Party App

Installing an App with appInstall mutation creates an App based on its manifest URL.

This mutation is only available to staff users with the MANAGE_APPS permission. Staff user can't grant app more permissions than he has for his own.

The mutation takes the following input fields:

• appName: the name of the App, required.
• manifestUrl: URL of the manifest file, required.
• permissions: list of permissions the app should be granted.
• activateAfterInstallation: immediately activate the new App. Default true.

The response of the mutation contains the appInstallation which contains all information about installation process.

mutation{
  appInstall(
      input: {
        appName: "External Order App", 
        manifestUrl: "http://localhost:3000/manifest", 
        permissions:[MANAGE_ORDERS]
      }
  ) {
    appInstallation{
      id
      status
      appName
      manifestUrl
    }
    appErrors{
      field
      message
      code
      permissions
    }
  }
}

Show more ↓

If there are no errors in the response, a new app installation process is created:

{
  "data": {
    "appInstall": {
      "appInstallation": {
        "id": "QXBwT25nb2luZ0luc3RhbGxhdGlvbjoz",
        "status": "PENDING",
        "appName": "Order App",
        "manifestUrl": "http://localhost:3000/manifest"
      },
      "appErrors": []
    }
  }
}

The chart below explains workflow of the installation process:

Schedule installation

Retrieving ongoing installations

To fetch all ongoing and failed installations, use the appsInstallations query. This query is only available to staff users with the MANAGE_APPS permission. The query returns list of AppInstallation objects.

{
  appsInstallations{
    id
    status
    appName
  }
}

The query returns a similar response:

{
  "data": {
    "appsInstallations": [
      {
        "id": "QXBwT25nb2luZ0luc3RhbGxhdGlvbjoy",
        "status": "FAILED",
        "appName": "Shipping App"
      },
      {
        "id": "QXBwT25nb2luZ0luc3RhbGxhdGlvbjoz",
        "status": "PENDING",
        "appName": "Order App"
      }
    ]
  }
}

Retrying failed installation

If the appsInstallations query returns App with failed status, there is a possibility to retry the installation process. This mutation is only available to staff users with the MANAGE_APPS permission. Staff user can't retry app installation if app requires more permissions than he has for his own. The appRetryInstall mutation will run the installation process for a given app.

The mutation takes the following fields:

• id: the id of the AppInstallation, required.
• activateAfterInstallation: immediately activate the new App. Default true.

Example of retrying installation of app with id QXBwT25nb2luZ0luc3RhbGxhdGlvbjoy:

 mutation{
  appRetryInstall(id:"QXBwT25nb2luZ0luc3RhbGxhdGlvbjoy"){
    appErrors{
      field
      message
      code
    }
    appInstallation{
      id
      status
    }
  }
}

Deleting failed installation

If the appsInstallations query returns App with failed status, there is a possibility to delete failed installation. This mutation is only available to staff users with the MANAGE_APPS permission. The appDeleteFailedInstallation mutation will delete failed installation.

The mutation takes the following fields:

• id: the id of the AppInstallation, required.

Local Apps

Creating an App

To create a new app, use the appCreate mutation. This mutation is only available to staff users with the MANAGE_APPS permission. Staff user can't grant app more permissions than he has for his own. The mutation takes the following input fields:

• name: the name of the app.
• isActive: whether to activate the app, defaults to true.
• permissions: list of permissions the app should be granted.

Let's assume that we want to create an order processing service that can fetch and manage orders in Nautical. To do so, we create a new app with the MANAGE_ORDERS permission:

mutation {
  appCreate(
    input: { name: "Order processing service", permissions: [MANAGE_ORDERS] }
  ) {
    authToken
    app {
      id
      name
    }
    appErrors {
      field
      code
    }
  }
}

If there are no errors in the response, a new app is created:

{
  "data": {
    "appCreate": {
      "authToken": "Es1O0oB2O3PTeG9A4IVYUcaMoru3Ls",
      "app": {
        "id": "QXBwOjk=",
        "name": "Order processing service"
      },
      "appErrors": []
    }
  }
}

The response contains the authToken field - this is the token that the app needs to include in requests to Nautical API to authorize itself and have access to queries or mutations that it needs.

note

The authToken field is only available in the mutation response and cannot be fetched later, except for the last four digits.

Creating authorization keys

Creating an app with appCreate mutation creates the default authorization token (authToken). You can create more authorization keys with the appTokenCreate. The mutation takes the following fields:

• app: ID of the app.
• name: (optional) name of the key.

mutation {
  appTokenCreate(input: { app: "QXBwOjk=" }) {
    authToken
    appErrors {
      field
      code
    }
    appToken {
      id
    }
  }
}

Revoking authorization keys

To revoke an authorization key, use the appTokenDelete:

mutation {
  appTokenDelete(id: "QXBwOjk=") {
    appErrors {
      field
      code
  }
}

Retrieving all Apps

To fetch list of all apps, use apps query. This query is only available to staff users with the MANAGE_APPS permission.

{
  apps(first: 5){
    edges{
      node{
        id
        permissions{
          code
        }
        name
        isActive
        webhooks{
          name
        }
        
      }
    }
  }
}

The query returns a similar response:

{
  "data": {
    "apps": {
      "edges": [
        {
          "node": {
            "id": "QXBwOjE=",
            "permissions": [
              {
                "code": "MANAGE_ORDERS"
              }
            ],
            "name": "Order App",
            "isActive": true,
            "webhooks": []
          }
        }
      ]
    }
  }
}

Show more ↓

Activating an App

To activate an app, use the appActivate mutation. This mutation is only available to staff users with the MANAGE_APPS permission. Staff user can't activate app which has more permissions than he has for his own.

The mutation takes the following fields:

• id: the id of the App, required.

mutation {
  appActivate(id:"QXBwOjE="){
    app{
      id
      isActive
    }
    appErrors{
      field
      message
      code
    }
  }
}

The query returns a similar response:

{
  "data": {
    "appActivate": {
      "app": {
        "id": "QXBwOjE=",
        "isActive": true
      },
      "appErrors": []
    }
  }
}

Deactivating an App

To deactivate an app, use the appDeactivate mutation. This mutation is only available to staff users with the MANAGE_APPS permission. Staff user can't deactivate an app which has more permissions than they have for their own.

note

Deactivating an app will disable all auth-tokens generated for an app. The app won't receive a webhook payload.

The mutation takes the following fields:

• id: the id of the App, required.

mutation {
  appDeactivate(id:"QXBwOjE="){
    app{
      id
      isActive
    }
    appErrors{
      field
      message
      code
    }
  }
}

The query returns a similar response:

{
  "data": {
    "appDeactivate": {
      "app": {
        "id": "QXBwOjE=",
        "isActive": false
      },
      "appErrors": []
    }
  }
}

Subscribing to a webhook

To subscribe to a webhook, we need to first create an app with proper permissions. Let's assume that we want to extend the order processing app that we've created in the example above. The app should receive notifications whenever new orders are created in Nautical. To do so, we'll create a new webhook using the webhookCreate mutation. The mutation takes the following input:

• name: name of the webhook.
• targetUrl: URL of a service that will receive webhooks requests.
• events: list of the events to subscribe to.
• app: ID of the app to which the webhook belongs.
• isActive: whether to activate the webhook.

mutation {
  webhookCreate(
    input: {
      name: "New orders notification"
      targetUrl: "https://order-processing-service.example.com"
      events: [ORDER_CREATED]
      app: "QXBwOjk="
      isActive: true
      secretKey: "secret-key"
    }
  ) {
    webhook {
      id
    }
    webhookErrors {
      field
      code
    }
  }
}

Show more ↓

If there are no errors in the response, the webhook is successfully created. From now on, whenever a new order is placed, payload with order data will be sent to your targetUrl.

Updating a webhook

To update a webhook (e.g. to deactivate it or change the permissions), use the webhookUpdate mutation. The mutation takes similar input fields as the webhookCreate mutation. The example below shows how to deactivate a webhook:

mutation {
  webhookUpdate(id: "V2ViaG9vazox", input: { isActive: false }) {
    webhook {
      isActive
    }
    webhookErrors {
      field
      code
    }
  }
}

Removing a webhook

To fully remove a webhook, use the webhookDelete mutation:

mutation {
  webhookDelete(id: "V2ViaG9vazox") {
    webhookErrors {
      field
      code
    }
  }
}