Authentication

Oauth2.0

For Sumup POS Pro authentication we are using the Oauth 2.0 protocol. We are supporting only one authorization flow : authorization code.

Authorize endpoint: https://oauth.api.tiller.systems/oauth2/authorize
Token endpoint: https://oauth.api.tiller.systems/oauth2/token

The chosen flow will grant you an access_token for accessing Sumup POS Pro API resources. All requests must includes the following header:

Authorization: Bearer <YOUR_TOKEN>

Authorization Code Flow

You will need your user to Login in with us using the following Login URL:
https://oauth.api.tiller.systems/login?client_id=YOUR_CLIENT_ID&response_type=code&scope=SCOPES&redirect_uri=YOUR_CALLBACK_URL

• Your clientId can be found inside the tech configuration on your application (AppMarket > My Integrations).
• The scopes needed by your application to correctly work.
• The callbackURL is the one where you will received the code to call the /token endpoint and retrieve the user access_token and refresh_token. Use them to call our API as your client. It MUST be the same one you set in your tech configuration on your application

Once that is done, your user will be redirected to your callbackURL with the param code. You must then request for the user code to be translated to a token:

curl

curl --request POST \
     --header "Content-type: application/x-www-form-urlencoded" \
     --url "https://oauth.api.tiller.systems/oauth2/token?grant_type=authorization_code&redirect_uri=<callback_url>&client_id=<client_id>&client_secret=<client_secret>&code=<code>"

In response you should have an access_token that expires in 60 minutes and a refresh_token that expires in 60 days.
To re-generate an access_token from a refresh_token, you need to make this request:

curl

curl --request POST \
     --header "Content-type: application/x-www-form-urlencoded" \
     --url "https://oauth.api.tiller.systems/oauth2/token?grant_type=refresh_token&client_id=<client_id>&client_secret=<client_secret>&refresh_token=<token>"

Flow schema

Here is a schema of the authentication flow

Scopes

Depending the API you need access to, you will need different scope. Here is a list of scope / API :

• These scopes are enabled by default

API	Scope
Order	order/write order/read
Purchase Request	purchase-request/write

• These scopes are not enabled by default. Please reach out to support to enable the scopes you need for your integration

API	Scope
Store	store/read
Location	location/read
Catalog	catalog/read