Create credentials for a self-hosted app

A Zettle self-hosted app is hosted by one or more individual merchants. Authorisation is done using the assertion grant method.

With this method, an API key is created by the Zettle merchant account owner. The API key contains merchant identity information, and is shared with the developer building the app. The API key is in the form of a JSON web token (JWT) assertion. This key is used directly to request an access token from the authorisation server, and get access to the merchant’s data. The API key is valid until the merchant revokes it.

With assertion grant authorisation, client app usage tracking is not available by default, but can be set up using tracking endpoints (optional). See the following how to do this.

To use the assertion grant method, you need to ask the Zettle merchant account owner to create an API key at my.zettle.com. You can provide the merchant with a link to the API creation page, or steps to create an API key. See the following how to do this.

Note: To build an app that will be hosted by you as an integrator, see create credentials for a partner-hosted app.

• An account for the Developer Portal. If you don't have this, sign up for a developer account.

Follow these steps to require the API key from the merchant that will use your app.

1. Ask the merchant to create an API key in one of the following ways:
   • Provide a link with pre-populated fields and instructions to create an API key with the link.

     https://my.zettle.com/apps/api-keys?name=<key-name>&scopes=<scopes>
     

     Where:
     • <key-name> is the name under which the API key is stored. Keep it short and descriptive. A good practice is to use the integration name as the key name, for example, WooCommerce.
     • <scopes> contains the list of needed OAuth scopes separated by a space, for example, READ:PURCHASE%20READ:FINANCE. Example:

       https://my.zettle.com/apps/api-keys?name=WooCommerce&scopes=READ:PURCHASE%20READ:FINANCE
       

   • Provide OAuth scopes and instructions to create an API key with the OAuth scopes.
2. Ask the merchant to share the created API key and client ID with you.

App tracking collects data about your app. To track a self-hosted app, you need to use the following:

• The API key from the merchant
• The client ID of a partner-hosted app

Note: The client ID that you receive from the merchant cannot be used to track a self-hosted app. You need to use the client ID of a partner-hosted app instead.

Prepare for tracking of a self-hosted app:

1. Create credentials for a partner-hosted app.
2. When setting up the authorisation assertion grant flow, use the client ID of the partner-hosted app.

• Set up authorisation assertion grant

• OAuth API Reference