Skip to content

Commit 849110b

Browse files
matoousmatoous
committed
feat(docs): improve oauth2 documentation
1 parent 509da55 commit 849110b

1 file changed

Lines changed: 122 additions & 89 deletions

File tree

  • src/content/docs/tools/authorization

‎src/content/docs/tools/authorization/oauth.mdx‎

Lines changed: 122 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -32,20 +32,11 @@ SumUp strongly recommends that you rely on [reputable existing libraries](https:
3232

3333
Choose the flow that matches how your application obtains access while keeping scope verification requirements in mind.
3434

35-
<Aside type="caution">
36-
37-
SumUp manually verifies requests for the following scopes:
38-
39-
- `payments` – required to create and process payments.
40-
- `payment_instruments` – required to store customer data and tokenize cards.
41-
42-
[Contact us](/contact) to request those scopes for your application.
43-
44-
</Aside>
45-
4635
## Authorization Code Flow
4736

48-
This flow implements the [RFC 6749 Authorization Code Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1). It lets a SumUp merchant review the permissions you request and authorize your application accordingly. The [requested scopes](#authorization-scopes) determine the allowed actions.
37+
This flow implements the [RFC 6749 Authorization Code Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1). It lets a SumUp user review the permissions you request and authorize your application accordingly. The [requested scopes](#authorization-scopes) determine the allowed actions.
38+
39+
Use this flow when your application has a backend that can keep the client secret confidential. The flow separates user authorization from token issuance, so your application never sends the user's credentials to your own systems.
4940

5041
<Steps>
5142

@@ -57,21 +48,38 @@ This flow implements the [RFC 6749 Authorization Code Grant](https://datatracker
5748
</Aside>
5849

5950
3. After the user approves, SumUp redirects to your **Redirect URI** with an authorization code and the original `state`.
60-
4. Your application exchanges the authorization code for tokens by calling the token endpoint described below.
51+
4. Your application verifies the returned `state` and exchanges the authorization code for tokens by calling the token endpoint described below.
6152
5. Use the `access_token` in the `Authorization: Bearer` header when calling SumUp APIs.
6253

6354
</Steps>
6455

56+
When building this flow:
57+
58+
- Register the exact redirect URIs your application uses and send the same `redirect_uri` value in the authorization request and token exchange.
59+
- Always send a `state` value and verify that the callback returns the same value before exchanging the code.
60+
- Treat the authorization code as short-lived and single-use. Exchange it immediately from your backend and never reuse it.
61+
62+
Example authorization request:
63+
64+
```http
65+
GET /authorize?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope=payments%20customers%20payment_instruments&state={STATE} HTTP/1.1
66+
Host: api.sumup.com
67+
```
68+
6569
### Exchange the Authorization Code
6670

67-
Send the following request to `https://api.sumup.com/token`:
71+
After the user is redirected back to your application, read the `code` and `state` query parameters from the callback URL. If the `state` matches the value your application originally sent, exchange the authorization code at `https://api.sumup.com/token`:
6872

69-
```bash
70-
curl https://api.sumup.com/token \
71-
-X POST \
72-
-H "Content-Type: application/x-www-form-urlencoded" \
73-
-d "grant_type=authorization_code&code={AUTHORIZATION_CODE}&redirect_uri={REDIRECT_URI}" \
74-
-u "{CLIENT_ID}:{CLIENT_SECRET}"
73+
```http
74+
POST /token HTTP/1.1
75+
Host: api.sumup.com
76+
Content-Type: application/x-www-form-urlencoded
77+
78+
grant_type=authorization_code
79+
&code={AUTHORIZATION_CODE}
80+
&redirect_uri={REDIRECT_URI}
81+
&client_id={CLIENT_ID}
82+
&client_secret={CLIENT_SECRET}
7583
```
7684

7785
The response contains an access token, refresh token, and metadata such as token lifetime and granted scopes.
@@ -88,27 +96,65 @@ The response contains an access token, refresh token, and metadata such as token
8896

8997
### Refresh the Access Token
9098

91-
Access tokens expire, for example when a user changes their password or revokes access. Use the refresh token to request a new access token from `https://api.sumup.com/token` as defined by OAuth 2.0.
99+
Access tokens are short-lived. Use the `expires_in` value to track when the current access token is expected to expire. You can refresh shortly before expiry, or you can wait until an API request fails because the access token is no longer valid. In both cases, request a new token from `https://api.sumup.com/token` using the OAuth 2.0 refresh token grant:
100+
101+
```http
102+
POST /token HTTP/1.1
103+
Host: api.sumup.com
104+
Content-Type: application/x-www-form-urlencoded
105+
106+
grant_type=refresh_token
107+
&refresh_token={REFRESH_TOKEN}
108+
&client_id={CLIENT_ID}
109+
&client_secret={CLIENT_SECRET}
110+
```
111+
112+
Your integration should still handle cases where an API request fails because the access token became invalid earlier than expected, for example after revocation or other account changes.
113+
114+
The token endpoint responds with a new access token and may also return a new refresh token:
115+
116+
```json
117+
{
118+
"access_token": "{NEW_ACCESS_TOKEN}",
119+
"token_type": "Bearer",
120+
"expires_in": 3599,
121+
"refresh_token": "{NEW_REFRESH_TOKEN}"
122+
}
123+
```
124+
125+
Handle refresh tokens according to standard OAuth 2.0 practices:
92126

93-
Refresh tokens are valid for six months. If you use a refresh token within 30 days of its expiration, SumUp issues a new token that remains valid for another six months. The previous token keeps working until it expires, giving you time to rotate it across your systems.
127+
- Store refresh tokens securely because they are long-lived credentials.
128+
- After a successful refresh, persist and use the latest `refresh_token` returned by the token endpoint. If the response does not include a new `refresh_token`, continue using the one you already have.
129+
- If refresh fails with an OAuth error such as `invalid_grant`, treat the refresh token as no longer usable and restart the authorization code flow.
130+
- When refresh fails, do not keep retrying with the same invalid refresh token. Ask the user to authorize again.
94131

95132
## Authorization Scopes
96133

97134
Scopes restrict what your application may do on behalf of the merchant. Request only the scopes you need. When you omit scopes, SumUp grants the defaults listed below. To obtain additional scopes later, repeat the authorization code flow.
98135

99-
| Scope name | Default | Access Level | Description |
100-
| -------------------------------- | ------- | ------------ | ----------------------------------------------------------------------------------------- |
101-
| `transactions.history` | yes | merchant | View transactions and transaction history for the merchant user. |
102-
| `user.app-settings` | yes | merchant | View and modify SumUp mobile app settings for the merchant user. |
103-
| `user.profile_readonly` | yes | merchant | View profile details of the merchant user. |
104-
| `user.profile` | no | merchant | Modify profile details of the merchant user. |
105-
| `user.subaccounts` | no | merchant | View and modify sub-account profiles for the merchant user. |
106-
| `user.payout-settings` | no | merchant | View and modify payout settings for the merchant user. |
107-
| `products` | no | merchant | View and modify products, shelves, prices, and VAT rates in the merchant's product store. |
108-
| `restricted` payments | no | feature | Create and process payment checkouts. Requires manual verification by SumUp. |
109-
| `restricted` payment_instruments | no | feature | Save customers and tokenize their payment cards. Requires manual verification by SumUp. |
136+
| Scope name | Default | Access Level | Description |
137+
| ----------------------- | ------- | ------------ | ----------------------------------------------------------------------------------------- |
138+
| `transactions.history` | yes | merchant | View transactions and transaction history for the merchant user. |
139+
| `user.app-settings` | yes | merchant | View and modify SumUp mobile app settings for the merchant user. |
140+
| `user.profile_readonly` | yes | merchant | View profile details of the merchant user. |
141+
| `user.profile` | no | merchant | Modify profile details of the merchant user. |
142+
| `user.subaccounts` | no | merchant | View and modify sub-account profiles for the merchant user. |
143+
| `user.payout-settings` | no | merchant | View and modify payout settings for the merchant user. |
144+
| `products` | no | merchant | View and modify products, shelves, prices, and VAT rates in the merchant's product store. |
145+
| `payments`* | no | feature | Create and process payment checkouts. Requires manual verification by SumUp. |
146+
| `payment_instruments`* | no | feature | Save customers and tokenize their payment cards. Requires manual verification by SumUp. |
147+
148+
<Aside type="caution">
149+
150+
*SumUp manually verifies requests for the following scopes:
151+
152+
- `payments` – required to create and process payments.
153+
- `payment_instruments` – required to store customer data and tokenize cards.
154+
155+
[Contact us](/contact) to request those scopes for your application.
110156

111-
Restricted scopes must be enabled by SumUp for your application. [Contact us](/contact) to request them.
157+
</Aside>
112158

113159
## Client Credentials Flow
114160

@@ -120,88 +166,75 @@ Request an access token from `https://api.sumup.com/token` using the client cred
120166

121167
To integrate an external application with SumUp, register an OAuth application and generate client credentials. These credentials let you complete the OAuth flows in this guide and obtain access tokens for protected SumUp resources.
122168

123-
### Steps
124-
125-
This section walks through the registration process:
126-
127-
1. [Log in to your account](#1-log-in-to-your-account)
128-
2. [Create an OAuth application](#2-create-an-oauth-application)
129-
3. [Generate the client credentials](#3-generate-the-client-credentials)
130-
4. [Access the client credentials](#4-access-the-client-credentials)
131-
132169
### Before You Begin
133170

134-
Have the following ready before you register the application:
135-
136-
- A SumUp merchant account with completed [account details](https://me.sumup.com/account). Reach out through the [contact form](/contact) if you need a sandbox merchant account.
137-
- Your application name.
138-
- One or more redirect URIs. SumUp redirects users to these URIs after authentication and sends the authorization codes you exchange for tokens in the [authorization code flow](#authorization-code-flow).
171+
1. Prepare a SumUp merchant account with completed [account details](https://me.sumup.com/account).
172+
2. Choose your application name.
173+
3. Prepare one or more redirect URIs. SumUp redirects users to these URIs after authentication and sends the authorization codes you exchange for tokens in the [authorization code flow](#authorization-code-flow).
139174

140-
### 1. Log in to Your Account
141-
142-
Log in to [your SumUp account](https://me.sumup.com/login). Once logged in, **Account** appears in place of the **Log in** button at the top right.
175+
### Steps
143176

144-
### 2. Create an OAuth Application
177+
<Steps>
145178

146-
Navigate to the [OAuth Apps](https://me.sumup.com/developers/apps) page to create or manage OAuth applications.
179+
1. Log in to [your SumUp account](https://me.sumup.com/login). Once logged in, **Account** appears in place of the **Log in** button at the top right.
147180

148-
Select **Create application** at the bottom right to define your application.
181+
2. Navigate to the [OAuth Apps](https://me.sumup.com/developers/apps) page to create or manage OAuth applications.
149182

150-
<Image alt="Create OAuth App screen" src="/img/guides/create-oauth-apps.png" width="80%" />
183+
Select **Create application** at the bottom right to define your application.
151184

152-
Describe your application, provide its homepage, and select **Register application** to continue.
185+
<Image alt="Create OAuth App screen" src="/img/guides/create-oauth-apps.png" width="80%" />
153186

154-
You can edit the registered application by selecting it. The edit page lets you update details and add optional information such as a logo, terms and conditions, and privacy policy URLs.
187+
Describe your application, provide its homepage, and select **Register application** to continue.
155188

156-
You can also select the scopes your application requires. Each scope includes a short description of the access it grants.
189+
You can edit the registered application by selecting it. The edit page lets you update details and add optional information such as a logo, terms and conditions, and privacy policy URLs.
157190

158-
### 3. Generate the Client Credentials
191+
You can also select the scopes your application requires. Each scope includes a short description of the access it grants.
159192

160-
On the [OAuth Apps](https://me.sumup.com/developers/apps) page, open your application and choose **Create client secret**.
193+
3. On the [OAuth Apps](https://me.sumup.com/developers/apps) page, open your application and choose **Create client secret**.
161194

162-
<Image alt="Create new OAuth App credentials form" src="/img/guides/client-credentials-form.png" width="80%" />
195+
<Image alt="Create new OAuth App credentials form" src="/img/guides/client-credentials-form.png" width="80%" />
163196

164-
Provide the following details:
197+
Provide the following details:
165198

166-
| Name | Required | Description |
167-
| ----- | -------- | ---------- |
168-
| Client name | Yes | A descriptive name for your client application. |
169-
| Application type | Yes | The type of your client application. Options: Web, Android, iOS, Other. |
170-
| Authorized redirect URL | Yes | Redirect URL to register for your client application. Specify multiple URLs by separating them with commas. |
171-
| Authorized JavaScript Origin | No | Origin URI for browser-based web applications. SumUp enables CORS for registered origins. |
199+
| Name | Required | Description |
200+
| ----- | -------- | ---------- |
201+
| Client name | Yes | A descriptive name for your client application. |
202+
| Application type | Yes | The type of your client application. Options: Web, Android, iOS, Other. |
203+
| Authorized redirect URL | Yes | Redirect URL to register for your client application. Specify multiple URLs by separating them with commas. |
204+
| Authorized JavaScript Origin | No | Origin URI for browser-based web applications. SumUp enables CORS for registered origins. |
172205

173-
Select **Save** to generate the credentials. The **Client secrets** section lists each credential with its name, application type, and client ID.
206+
Select **Save** to generate the credentials. The **Client secrets** section lists each credential with its name, application type, and client ID.
174207

175-
<Aside type="note">
208+
<Aside type="note">
176209

177-
You can register as many client credentials as you need. Repeat this step to create additional ones.
210+
You can register as many client credentials as you need. Repeat this step to create additional ones.
178211

179-
</Aside>
212+
</Aside>
180213

181-
### 4. Access the Client Credentials
214+
4. After creation, credentials appear in the **Client credentials** section of your OAuth application.
182215

183-
After creation, credentials appear in the **Client credentials** section of your OAuth application (see screenshot).
216+
<Image alt="OAuth client credentials section" src="/img/guides/client-credentials-list.png" width="80%" />
184217

185-
<Image alt="OAuth client credentials section" src="/img/guides/client-credentials-list.png" width="80%" />
218+
Use the download button to receive a JSON file with the full credential details, for example:
186219

187-
Use the download button to receive a JSON file with the full credential details, for example:
220+
```json
221+
{
222+
"id": "CCCFAXYD",
223+
"name": "SA web client",
224+
"client_id": "fOcmczrYtYMJ7Li5GjMLLcUeC9dN",
225+
"client_secret": "717bd571b54297494cd7a79b491e8f2c1da6189c4cc2d3481380e8366eef539c",
226+
"application_type": "web",
227+
"redirect_uris": ["https://sample-app.example.com/callback"]
228+
}
229+
```
188230

189-
```json
190-
{
191-
"id": "CCCFAXYD",
192-
"name": "SA web client",
193-
"client_id": "fOcmczrYtYMJ7Li5GjMLLcUeC9dN",
194-
"client_secret": "717bd571b54297494cd7a79b491e8f2c1da6189c4cc2d3481380e8366eef539c",
195-
"application_type": "web",
196-
"redirect_uris": ["https://sample-app.example.com/callback"]
197-
}
198-
```
231+
<Aside type="note">
199232

200-
<Aside type="note">
233+
Store client secrets securely and never expose them publicly. If you suspect a secret was compromised, [contact us](/contact) immediately.
201234

202-
Store client secrets securely and never expose them publicly. If you suspect a secret was compromised, [contact us](/contact) immediately.
235+
</Aside>
203236

204-
</Aside>
237+
</Steps>
205238

206239
### Result
207240

0 commit comments

Comments
 (0)