Set up authorisation code grant

To build a partner-hosted app and integrate with Zettle APIs, the merchant must provide you with access to merchant data in Zettle. For a partner-hosted app, this is done by setting up the authorisation code grant flow. This uses a client ID and client secret for authorisation. The following describes how to set up this authorisation flow.

Prerequisites

Step 1: Initiate the authorisation flow

Redirect the merchant to the Zettle authorisation flow. The merchant will authorise the access request from the app in the authorisation flow.

  1. Present the following URL in a browser. The redirect_uri must be the one you provided when creating the partner-hosted app.

    1
    https://oauth.zettle.com/authorize?response_type=code&scope={oauth_scope}
    2
    &client_id={client_ID}&redirect_uri={redirect_uri}&state={state_value}

    Example: An initiating URL from which the merchant can authorise the app with read and write access to the merchant's product library.

    Request

    1
    https://oauth.zettle.com/authorize?response_type=code&scope=READ:PRODUC
    2
    T%20WRITE:PRODUCT&client_id=6adde977-c34d-4de1-99b2-
    3
    f6ed3e65431a&redirect_uri=https%3A%2F%2Fwww.example.com%2Fzettle%2Fretu
    4
    rn&state=abc123678
  2. The merchant gets authenticated and authorises the app for data access. When done, the merchant is redirected by the authorisation server to the redirect_uri, together with a temporary authorisation code.

    1
    https://www.example.com/get?code=4fa87ba8cc7f30e91ad2ab1ad21c1b3e&state=abc123678

Step 2: Retrieve access and refresh tokens

Use the temporary authorisation code to retrieve a short-lived access token for first-time access. When it's retrieved, a long-lived refresh token is also returned. The refresh token is used to generate a new access token.

Note: The authorisation code to retrieve the access token and refresh token can only be used once.

  1. Retrieve access token and refresh token using the authorisation code.

    1
    curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=authorization_code&&code={authorisation_code}&client_secret={client_secret}&client_id={client_ID}" https://oauth.zettle.com/token

    Example: Retrieval of an access token and refresh token using the authorisation code. The access token is valid for 7200 seconds, and the refresh token is valid for 180 days.

    Request

    1
    curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=authorization_code&code=4fa87ba8cc7f30e91ad2ab1ad21c1b3e&client_secret=7356b8a1-75ac-4336-970b-bef63cd219c1&client_id=c55de605-48b6-42ef-b69e-cd9d14ded15a" https://oauth.zettle.com/token

    Response

    1
    {
    2
    "access_token": "eyJraWQiOiIxNDQ0NzI3MTY0Njk4Iiwi...yZA",
    3
    "refresh_token": "IZSEC07b0edfc-f557-4e52-a995-384288e2351e",
    4
    "expires_in": 7200
    5
    }
  2. Save the refresh token for generating a new access token when it expires.

Step 3: Generate new access token

Note: When a new access token is generated, a new refresh token is also generated. Even though a refresh token is valid for 180 days, it's recommended to use the new refresh token in the next request for generating a new access token.

  1. Use the refresh token to generate a new access token.

    1
    curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=refresh_token&refresh_token={refresh_token}&client_secret={client_secret}&client_id={client_ID}" https://oauth.zettle.com/token

    Example: Retrieval of a new access token using the refresh token.

    Request

    1
    curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=refresh_token&refresh_token=IZSEC90590831-93a5-4289-ee37-a17824c0fea1&client_secret=IZSECe8b27fdb-faea-46e1-a886-6eded9f84f72&client_id=6adde977-c34d-4de1-99b2-f6ed3e65431a" https://oauth.zettle.com/token

    Response

    1
    {
    2
    "access_token": "eyJraWQiOiIxN...R5Y6FDNTva7esJ5Q",
    3
    "refresh_token": "IZSEC07b0edfc-f557-4e52-a995-384288e2351e",
    4
    "expires_in": 7200
    5
    }
  2. Save the new refresh token.

  3. In the next request for generating a new access token, use the new refresh token instead of reusing the current refresh token.

Previous step