# Merchant Self-Authorization Integration Guide

## Overview

Merchant self-authorization is an authorization mechanism based on the OAuth 2.0 protocol. It enables developers to facilitate merchant authorization through a standardized process, without contacting the Keeta team for manual processing. The entire authorization process is secure and efficient.

Keeta provides two integration modes for developers who need automated token acquisition:

- **Server Callback Mode:** Keeta pushes the authorization code directly to a Webhook URL via HTTP GET. This mode is suitable for vendors who do not have merchant-facing frontend pages.
- **Standard OAuth 2.0 Mode:** Keeta redirects the merchant's browser to a `redirectUri` developers specify in the authorization link, carrying the authorization code as a query parameter. This mode is suitable for developers who have their own frontend pages and want merchants to land on their system after completing authorization.


The following sections walk through each mode in detail, covering the full authorization workflow and integration steps.

**Related APIs & Webhooks**

The following APIs and Webhook events are involved in this flow. Refer to the linked references for request parameters, response fields, and signature verification details.

- **Authorization Code Notification Webhook(Event ID: 1):** The Webhook notification, bringing auth code, sent by Keeta to the vendor's configured Webhook URL after merchant authorization. [View reference](/apis/standard/basic/webhooks/oauth2authorizationcodenotification)
- **Get Token API:** Exchange the authorization code for an access token and refresh token. [View reference](/apis/standard/basic/endpoints/oauthtoken)
- **Get Merchant Authorization Information API:** Retrieve the brand ID and authorized store list after obtaining the access token. [View reference](/apis/standard/basic/endpoints/getauthorizedresources)


## Server Callback Mode

In Server Callback Mode, the authorization code is delivered server-to-server. The developer configures a Webhook URL for Event ID 1 in the Developer Portal, then generates an authorization link and provides it to the merchant. After the merchant completes authorization on the Keeta merchant platform, Keeta sends the authorization code directly to the configured Webhook URL via HTTP GET. The developer's backend receives the code and exchanges it for an access token — no frontend page is involved on the developer's side.

**Configuring the webhook URL**

In the Developer Portal, open **Application Management / Edit Application**. Under Push Oauth2 authorization code, enter the redirect URL in the Webhook URL field. This is the base domain Keeta will redirect to after merchant authorization.

![image.png](/assets/selfauthor10.535f02ce16cb500f4fc4c20c17e713a9853b06d11235d4fbade645fd0512f6ae.e9420925.png)
![image.png](/assets/selfauthor11.510d8959163a9aa0f73374018f7fb7997fbe179f55862c2b3f239b76ee2397ca.e9420925.png)
**Workflow**


```mermaid
sequenceDiagram
    participant Merchant as Merchant
    participant DevServer as Vendor
    participant Keeta as Keeta Open Platform
    participant KeetaMerchant as Keeta Merchant Portal

    DevServer->>Keeta: Configure Webhook URL for Event ID 1 in Developer Portal
    DevServer->>Merchant: Send OAuth authorization link
    Merchant->>KeetaMerchant: Authorize account and select stores
    KeetaMerchant->>Keeta: Forward authorization confirmation
    Keeta->>DevServer: Send auth code via Webhook (Event ID 1)
    DevServer->>Keeta: Exchange auth code for access token (POST /base/oauth/token)
    Keeta-->>DevServer: Issue access token
    DevServer->>Keeta: Get brand ID / authorized stores (GET /api/open/base/authorized/resource/get)
    Keeta-->>DevServer: Return authorized stores
    DevServer->>DevServer: Map Keeta stores in vendor system
```

## Standard OAuth 2.0 Authorization Mode

In Standard OAuth 2.0 Mode, the authorization code is delivered via browser redirect. The developer would need to concatenate an authorization link with a `redirectUri` and `state` parameter and distribute to merchants. After the merchant completes authorization on the Keeta merchant platform, Keeta redirects the merchant's browser to the specified `redirectUri` with the authorization code appended as a query parameter. The developer's frontend page captures the code and passes it to the backend to exchange for an access token.

**Concatenating the authorization link**

The base authorization link can be obtained by clicking **Add Authorization** on the Application Management page. The developer then appends `redirectUri` and `state` to the link before sending it to the merchant.

- Base link:



```
merchant.mykeeta.com/m/web/openapi/authorize?responseType=authorization_code&appId=YOUR_APP_ID&redirectUri=&state=&scope=all
```

- Modified link (with `redirectUri` and `state` filled in, parameter order does not matter):



```
merchant.mykeeta.com/m/web/openapi/authorize?responseType=authorization_code&appId=YOUR_APP_ID&redirectUri=https://your-site.com/auth/callback&state=YOUR_STATE&scope=all
```

The `redirectUri` is the exact page on the developer's site where the merchant should land after authorization. The `state` is an opaque value defined by the developer, returned unchanged by Keeta, useful for identifying which merchant or session initiated the flow.

**Configuring the redirect URL**

Keeta requires vendor developers to configure the same `redirectUri` under the Push Oauth2 authorization code for security purposes.

![image.png](/assets/selfauthor11.510d8959163a9aa0f73374018f7fb7997fbe179f55862c2b3f239b76ee2397ca.e9420925.png)
**Workflow**


```mermaid
sequenceDiagram
    participant Merchant as Merchant
    participant DevFrontend as Vendor Frontend
    participant DevServer as Vendor Backend
    participant Keeta as Keeta Open Platform
    participant KeetaMerchant as Keeta Merchant Portal

    DevServer->>Keeta: Configure redirect URL in Developer Portal
    DevFrontend->>Merchant: Send OAuth authorization link (with redirectUri & state)
    Merchant->>KeetaMerchant: Authorize account and select stores
    KeetaMerchant->>Keeta: Forward authorization confirmation
    Keeta-->>Merchant: Redirect browser to redirectUri?code=AUTH_CODE&state=...
    Merchant->>DevFrontend: Browser lands on redirectUri with auth code
    DevFrontend->>DevServer: Pass auth code to backend
    DevServer->>Keeta: Exchange auth code for access token (POST /base/oauth/token)
    Keeta-->>DevServer: Issue access token
    DevServer->>Keeta: Get brand ID / authorized stores (GET /api/open/base/authorized/resource/get)
    Keeta-->>DevServer: Return authorized stores
    DevServer->>DevServer: Map Keeta stores in vendor system
```

## Managing Authorization Changes

Once a merchant has completed authorization, they can manage the authorized store scope at any time through the Keeta Merchant Portal: adding stores, removing stores, or fully revoking brand authorization. Keeta notifies the vendor's system of these changes in real time via Webhook, so the vendor can keep its local store mapping synchronized.

Vendors who have integrated merchant self-authorization **should subscribe to these events** to ensure their system always reflects the current authorized store scope.

**Store Authorization Change (Event ID 1301 / 1302)**


```mermaid
sequenceDiagram
    participant Merchant as Keeta Merchant Portal
    participant Keeta as Keeta Open Platform
    participant VendorWebhook as Vendor Webhook Endpoint
    participant VendorDB as Vendor Local Auth Data

    Merchant->>Keeta: Add / remove store authorization
    Keeta->>Keeta: Update authorization record and store mapping

    alt Add store authorization
        Keeta->>VendorWebhook: POST authorization change notification (Event ID 1301)
    else Remove store authorization
        Keeta->>VendorWebhook: POST authorization change notification (Event ID 1302)
    end

    VendorWebhook->>VendorWebhook: Parse appId / shopId / shopName / authId / createTime / opType
    VendorWebhook->>VendorDB: Update local store authorization mapping
    VendorDB-->>VendorWebhook: Update complete
    VendorWebhook-->>Keeta: HTTP 200
```

br
**Brand Authorization Removal (Event ID 1303)**


```mermaid
sequenceDiagram
    participant Merchant as Keeta Merchant Portal
    participant Keeta as Keeta Open Platform
    participant VendorWebhook as Vendor Webhook Endpoint
    participant VendorDB as Vendor Local Auth Data

    Merchant->>Keeta: Revoke brand authorization
    Keeta->>Keeta: Update authorization record
    Keeta->>VendorWebhook: POST brand authorization removal notification (Event ID 1303)
    VendorWebhook->>VendorDB: Invalidate access token and mark all stores as unauthorized
    VendorDB-->>VendorWebhook: Update complete
    VendorWebhook-->>Keeta: HTTP 200
```

To receive these notifications, configure a callback URL for each event in the Developer Portal under **Edit Application → Webhook Configuration**.

- When a merchant adds stores to an existing brand authorization, Keeta sends **Event ID 1301**. [View reference](/apis/standard/basic/webhooks/storeauthorizationnotification)
- When a merchant removes stores from an existing brand authorization, Keeta sends **Event ID 1302**. [View reference](/apis/standard/basic/webhooks/storeauthorizationremovalnotification)
- When a merchant fully revokes authorization for a brand, Keeta sends **Event ID 1303**. Upon receiving this notification, the vendor's system should treat the associated access token as invalid. [View reference](/apis/standard/basic/webhooks/brandauthorizationremovalnotification)