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.

• A developer account for the Developer Portal. If you don't have this, see sign up for a developer account.
• Credentials for the app. If you don't have these, see create credentials for a partner-hosted app.

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.

   Copy
   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

   Copy
   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.

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

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.

   Copy
   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}&redirect_uri={redirect_uri}" 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

   Copy
   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&redirect_uri=https://www.example.com" https://oauth.zettle.com/token

   Response

   Copy
   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.

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.

   Copy
   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

   Copy
   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

   Copy
   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.

• Create credentials for a partner-hosted app

• OAuth API Reference