OAuth API reference
The OAuth API provides the authorisation service for integrations with Zettle to handle authentication and authorisation of Zettle merchants to get access to their Zettle merchant account data.
It implements the OAuth 2.0 protocol.
https://oauth.zettle.com
Not applicable
Using authorisation assertion grant, authentication and authorisation is done with a JSON web token (JWT) assertion to request an access token from the authorisation server.
Ask your app users to create an API key (assertion) and share it with you for the following purposes:
- They authenticate as valid Zettle merchants by logging into my.zettle.com with their Zettle merchant accounts.
- They authorise requested access to their Zettle merchant account data for the app by creating an API key.
To retrieve the first access token, use the API key (assertion) and client ID from your app users.
An access token expires in 7200 seconds (2 hours). After it's expired, use the same API key and client ID to retrieve a new access token.
Note: The API key may be revoked by your app users at my.zettle.com. When the request fails, check whether the API key is still valid.
1POST /token
1{2grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&3client_id={client_ID}&4assertion={API_key}5}
See example Retrieve an access token (assertion grant).
Parameters
Click to hide request parameters.
Name | Type | In | Required/Optional | Description |
---|---|---|---|---|
grant_type | string | object | required | Always set to urn:ietf:params:oauth:grant-type:jwt-bearer to indicate an API key (assertion) is used to exchange for an access token. A JSON web token (JWT) assertion is used as an API key. |
client_id | string | object | required | An app credential that you get after creating credentials for a self-hosted app at my.zettle.com. |
Responses
Click to hide HTTP status codes.
Status code | Description |
---|---|
200 OK | Returned when the operation is successful. |
400 Bad Request | Returned when a parameter in the request has an invalid value. The API key may be revoked by your app users at my.zettle.com. |
Click to hide response attributes.
Name | Type | Description |
---|---|---|
access_token | string | The access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours). |
expires_in | string | Remaining lifetime of an access token in seconds. |
Using authorisation code grant, authentication and authorisation is done with a temporary authorisation code to exchange for an access token from the authorisation server.
In a browser, show your app users a login page where they authenticate themselves as valid Zettle merchants by logging into their Zettle merchant accounts. Then they will be asked to authorise your app access to their Zettle merchant data. They will see the app requested access on the login page.
1GET /authorize?response_type=code&2scope={oauth_scope}&3client_id={client_ID}&4redirect_uri={redirect_uri}&5state={state_value}
After your users authenticate themselves as valid Zettle merchants by logging to their Zettle merchant accounts, the users will be shown with requested access and an
After they press the button, the users will be redirected to the app with an authorisation code.
https://www.example.com/get?code=4fa87ba8cc7f30e91ad2ab1ad21c1b3e&state=abc123678
See example Ask app users to authenticate and authorise (code grant).
Parameters
Click to hide request parameters.
Name | Type | In | Required/Optional | Description |
---|---|---|---|---|
response_type | string | query | required | Always set to code to indicate an authorisation code is returned as the response. |
scope | string | query | required | Space-separated list of oauth scopes for requesting permissions to your users' Zettle merchant account data. For example, the list of scope READ:PRODUCT%20WRITE:PRODUCT means that your app requests to have a read and write access to your app users' Zettle product libraries. |
client_id | string | query | required | An app credential that you get after creating credentials for a partner-hosted app on Zettle Developer Portal. |
redirect_uri | string | query | required | A URL that starts with https and includes a redirect URI to direct your app users back to your app, after they authorise it to access their Zettle merchant data. For example, https://awesomeapp.com . |
state | string | query | required | A transparent session key to be included in the redirect. For example, abc123678-222. Make sure to apply URL encoding when providing complex data structures. |
Responses
Click to hide HTTP status codes.
Status code | Description |
---|---|
200 OK | Returned when the operation is successful. |
400 Bad Request | Returned when the operation contains invalid parameters. |
405 Method Not Allowed | Returned when the operation is not allowed. |
After your app gets authorised access to user' Zettle merchant account data, an authorisation code is returned. Use that code and your app credentials to retrieve the first access and refresh tokens.
1POST /token
1{2grant_type=authorization_code&3redirect_uri={redirect_uri}&4code={authorization_code}&5client_secret={client_secret}&6client_id={client_ID}7}
See example Retrieve the first access and refresh tokens (code grant).
Parameters
Click to hide request parameters.
Name | Type | In | Required/Optional | Description |
---|---|---|---|---|
grant_type | string | object | required | Always set to authorization_code to indicate an authorisation code is used to exchange for an access token. |
redirect_uri | string | object | required | A URL that includes a redirect URI to direct your app users back to your app, after they authorise it to access their Zettle merchant data. For example, https://awesomeapp.com . |
code | string | object | required | An authorisation code that is returned, after your user authenticates themselves as a valid Zettle merchants and then authorises your app access to their Zettle merchant data. For example, ccf62ef9-99b2-4e9d-dba3-9c3f3c532992 . |
client_secret | string | object | required | An app credential that you get after creating credentials for a partner-hosted on Zettle Developer Portal. |
client_id | string | object | required | An app credential that you get after creating credentials for a partner-hosted app on Zettle Developer Portal. |
Responses
Click to hide HTTP status codes.
Status code | Description |
---|---|
200 OK | Returned when the operation is successful. |
400 Bad Request | Returned when a parameter in the request has an invalid value. |
Click to hide response attributes.
Name | Type | Description |
---|---|---|
access_token | string | The access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours). |
expires_in | string | Remaining lifetime of an access token in seconds. |
refresh_token | string | A refresh token that is used to exchange for the next access token, when it's expired. A refresh token has a lifetime of 180 days. |
An access token has a lifetime of 7200 seconds (2 hours). After an access token expires, generate a new access token from the refresh token.
1POST /token
1{2grant_type=refresh_token&3refresh_token={Previously returned refresh token}&4client_secret={client_secret}&5client_id={client_ID}6}
See example Generate a new access token from the refresh token (code grant).
Parameters
Click to hide request parameters.
Name | Type | In | Required/Optional | Description |
---|---|---|---|---|
grant_type | string | object | required | Always set to refresh_token to indicate a refresh token is used to exchange for an access token. |
refresh_token | string | object | required | The refresh token that is retrieved previously. |
client_secret | string | object | required | An app credential that you get after creating credentials for a partner-hosted on Zettle Developer Portal. |
client_id | string | object | required | An app credential that you get after creating credentials for a partner-hosted app on Zettle Developer Portal. |
Responses
Click to hide HTTP status codes.
Status code | Description |
---|---|
200 OK | Returned when the operation is successful. |
400 Bad Request | Returned when a parameter in the request has an invalid value. |
Click to hide response attributes.
Name | Type | Description |
---|---|---|
access_token | string | The access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours). |
expires_in | string | Remaining lifetime of an access token in seconds. |
refresh_token | string | A refresh token that is used to exchange for the next access token, when it's expired. A refresh token has a lifetime of 180 days. A refresh token is generated everytime a new access token is generated with the last generated refresh token. Use the new refresh token to exchange for the next access token. |
Using authorisation code grant with Proof key for code exchange (PKCE), authentication and authorisation is done with PKCE to exchange for an access token from the authorisation server.
In a browser, show your app users a login page where they authenticate themselves as valid Zettle merchants by logging into their Zettle merchant accounts. Then they will be asked to authorise your app access to their Zettle merchant data. They will see the app requested access on the login page.
1GET /authorize?response_type=code&2scope={oauth_scope}&3client_id={client_ID}&4redirect_uri={redirect_uri}&5state={state_value}&6code_challenge={code_challenge}&7code_challenge_method={code_challenge_method}
After your users authenticate themselves as valid Zettle merchants by logging to their Zettle merchant accounts, the users will be shown with requested access and an
After they press the button, the users will be redirected to the app with an authorisation code.
https://www.example.com/get?code=4fa87ba8cc7f30e91ad2ab1ad21c1b3e&state=abc123678
See example Ask app users to authenticate and authorise (PKCE).
Parameters
Click to hide request parameters.
Name | Type | In | Required/Optional | Description |
---|---|---|---|---|
response_type | string | query | required | Always set to code to indicate an authorisation code is returned as the response. |
scope | string | query | required | Space-separated list of oauth scopes for requesting permissions to your users' Zettle merchant account data. For example, the list of scope READ:PRODUCT%20WRITE:PRODUCT means that your app requests to have a read and write access to your app users' Zettle product libraries. |
client_id | string | query | required | An app credential that you get after creating credentials for an SDK app on Zettle Developer Portal. |
redirect_uri | string | query | required | A URL that includes a redirect URI to direct your app users back to your app, after they authorise it to access their Zettle merchant data. For example, awesomeapp://zettlelogin . |
state | string | query | required | A transparent session key to be included in the redirect. For example, abc123678-222. Make sure to apply URL encoding when providing complex data structures. |
code_challenge | string | query | required | A code verifier that is encoded with encoding method Base64-URL-encoding or SHA256. A code verifier is a random string between 43 and 128 characters long. The random string is cryptographically created using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde). |
code_challenge_method | string | query | required | The encoding method that is used to encode a code verifier to create a code challenge. It can be either Base64-URL-encoding and SHA256. |
Responses
Click to hide HTTP status codes.
Status code | Description |
---|---|
200 OK | Returned when the operation is successful. |
400 Bad Request | Returned when the operation contains invalid parameters. |
405 Method Not Allowed | Returned when the operation is not allowed. |
After your app gets authorised access to user' Zettle merchant account data, an authorisation code is returned. Use that code and your app credentials to retrieve the first access and refresh tokens.
1POST /token
1{2grant_type=authorization_code&3code={authorization_code}&4code_verifier={code_verifier}&5client_id={client_ID}6}
See example Retrieve the first access and refresh tokens (PKCE).
Parameters
Click to hide request parameters.
Name | Type | In | Required/Optional | Description |
---|---|---|---|---|
grant_type | string | object | required | Always set to authorization_code to indicate an authorisation code is used to exchange for an access token. |
code | string | object | required | An authorisation code that is returned, after your user authenticates themselves as a valid Zettle merchants and then authorises your app access to their Zettle merchant data. For example, ccf62ef9-99b2-4e9d-dba3-9c3f3c532992 . |
client_verifier | string | object | required | The random string that is encoded to create a code challenge. It's between 43 and 128 characters long. |
client_id | string | object | required | An app credential that you get after creating credentials for an SDK app on Zettle Developer Portal. |
Responses
Click to hide HTTP status codes.
Status code | Description |
---|---|
200 OK | Returned when the operation is successful. |
400 Bad Request | Returned when a parameter in the request has an invalid value. |
Click to hide response attributes.
Name | Type | Description |
---|---|---|
access_token | string | The access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours). |
expires_in | string | Remaining lifetime of an access token in seconds. |
refresh_token | string | A refresh token that is used to exchange for the next access token, when it's expired. A refresh token has a lifetime of 180 days. |
An access token has a lifetime of 7200 seconds (2 hours). After an access token expires, generate a new access token from the refresh token.
1POST /token
1{2grant_type=refresh_token&3refresh_token={Previously returned refresh token}&4client_id={client_ID}5}
See example Generate a new access token from the refresh token (PKCE).
Parameters
Click to hide request parameters.
Name | Type | In | Required/Optional | Description |
---|---|---|---|---|
grant_type | string | object | required | Always set to refresh_token to indicate a refresh token is used to exchange for an access token. |
refresh_token | string | object | required | The refresh token that is retrieved previously. |
client_id | string | object | required | An app credential that you get after creating credentials for an SDK app on Zettle Developer Portal. |
Responses
Click to hide HTTP status codes.
Status code | Description |
---|---|
200 OK | Returned when the operation is successful. |
400 Bad Request | Returned when a parameter in the request has an invalid value. |
Click to hide response attributes.
Name | Type | Description |
---|---|---|
access_token | string | The access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours). |
expires_in | string | Remaining lifetime of an access token in seconds. |
refresh_token | string | A refresh token that is used to exchange for the next access token, when it's expired. A refresh token has a lifetime of 180 days. A refresh token is generated everytime a new access token is generated with the last generated refresh token. Use the new refresh token to exchange for the next access token. |
Fetches information about a user's organisation.
1GET users/self
See example Get user information.
None
Click to hide HTTP status codes.
Status code | Description |
---|---|
200 OK | Returned when the operation is successful. |
404 Not found | Returned when the request is invalid. |
Click to hide response attributes.
Name | Type | Description |
---|---|---|
uuid | string | Unique identifier for the user. |
organizationUuid | string | Unique identifier for the user's organization. |
Remove a Zettle merchant from your app by disconnecting them from the app. This can be useful to clean up registered webhooks and remove access.
1DELETE application-connections/self
See example Remove app from user.
None
Click to hide HTTP status codes.
Status code | Description |
---|---|
204 No Content | Returned when the operation is successful. |
404 Not found | Returned when the request is invalid. |
The following example retrieves an access token using the assertion grant flow. The response value expires_in
is the remaining lifetime of the access token in seconds. The access token is valid for 7200 seconds.
Request
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&client_id=6adde977-c34d-4de1-99b2-f6ed3e65431a&assertion=eyJraWQiOiIwIiwidHlwIjoiSl...y9V15QKjn4ZgKRumYb_ikw" https://oauth.zettle.com/token
Response
1{2"access_token": "eyJraWQiOiIxNDQ0NzI3MTY0Njk4Iiwi...yZA",3"expires_in": 72004}
The following example asks users of an app with a redirect URI to www.example.com
to authenticate themselves as valid Zettle merchants and authorise the app with read and write access to their product library.
https://oauth.zettle.com/authorize?response_type=code&scope=READ:PRODUC
T%20WRITE:PRODUCT&client_id=6adde977-c34d-4de1-99b2-
f6ed3e65431a&redirect_uri=https%3A%2F%2Fwww.example.com%2Fzettle%2Fretu
rn&state=abc123678
The following example shows that the users are redirected to the app with URL ww.example.com
and an authorisation code 4fa87ba8cc7f30e91ad2ab1ad21c1b3e&state=abc123678
.
https://www.example.com/get?code=4fa87ba8cc7f30e91ad2ab1ad21c1b3e&state=abc123678
The following example retrieves 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
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": 72005}
The following example retrieves a new access token using the refresh token. The access token is valid for 7200 seconds.
Request
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": 72005}
The following example initiating URL asks the merchant to authorise the app with read and write access to the merchant's payments and user information.
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
The following example shows that the users are redirected to the app with URL ww.example.com
and an authorisation code 4fa87ba8cc7f30e91ad2ab1ad21c1b3e&state=abc123678
.
https://www.example.com/get?code=4fa87ba8cc7f30e91ad2ab1ad21c1b3e&state=abc123678
The following example retrieves 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
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" https://oauth.zettle.com/token
Response
1{2"access_token": "eyJraWQiOiIxNDQ0NzI3MTY0Njk4Iiwi...yZA",3"refresh_token": "IZSEC07b0edfc-f557-4e52-a995-384288e2351e",4"expires_in": 72005}
The following example retrieves a new access token using the refresh token. The access token is valid for 7200 seconds.
Request
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
1{2"access_token": "eyJraWQiOiIxN...R5Y6FDNTva7esJ5Q",3"refresh_token": "IZSEC07b0edfc-f557-4e52-a995-384288e2351e",4"expires_in": 72005}
The following example gets information about an app user.
Request
GET users/self HTTP/1.1
Host: oauth.zettle.com
Authorization: Bearer eyJraWQiOiIxN...R5Y6FDNTva7esJ5Q
Response
1{2"uuid": "de305d54-75b4-431b-adb2-eb6b9e546014",3"organizationUuid": "ab305d54-75b4-431b-adb2-eb6b9e546013"4}
The following example removes the connection between the app and a user.
Request
DELETE application-connections/self HTTP/1.1
Host: oauth.zettle.com
Authorization: Bearer eyJraWQiOiIxN...R5Y6FDNTva7esJ5Q
Response
1204 No content