Set up authorisation code grant with PKCE

Proof key for code exchange (PKCE) is an OAuth 2.0 security extension for public clients on mobile devices. You can use it with the Zettle SDK payment apps for enhanced authorisation security.

Instead of using a client secret (requesting tokens), the PKCE method creates a code challenge and includes it in every authorisation request. The received authorisation code and code verifier is then used to request access and refresh tokens. As the code challenge is an encoded code verifier, tokens will be returned only when the code challenge matches the code verifier.

• 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 an SDK app.

1. Generate a code verifier that fulfills the following rules:

   • Cryptographically create a random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde).
   • Make sure that the string is between 43 and 128 characters long.

2. Create a code challenge by encoding the code verifier with Base64-URL-encoding and SHA256. Base64-URL-encoding uses URL-safe characters for Base64-encoding. For example, change + to -.

   BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
   

Include the code challenge in the authorisation request whenever a Zettle merchant authorises the access request from the app.

1. Present the the following URL in a browser to redirect the merchant to the authorisation flow. The redirect_uri must be the one you provided when creating the SDK app.

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

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

   Request

   Copy
   1
   https://oauth.zettle.com/authorize?response_type=code&scope=WRITE:PAYMENT%20READ:PAYMENT%20READ:CUSTOMER%20READ:USERINFO&client_id={client_ID}&redirect_uri={redirect_uri}&state=8787&code_challenge={code_challenge}&code_challenge_method=S256

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 the 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 can only be used once.

1. Retrieve the access and refresh tokens using the authorisation code. This call uses the code_verifier used to generate the code_challenge used in the previous call. Since we don't use a client secret, this code can be called from the client directly.

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

   Example: Retrieving 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&code_verifier=ab190879772...012988&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.

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_id={client_ID}" https://oauth.zettle.com/token

   Example: Retrieving 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_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 an SDK app

• OAuth API Reference