---
title: OAuth Activation Flow
description: Implementation guide for secure user-verified license activation
date: 2024-01-31
---

## Overview

The Secure OAuth Activation flow ensures that licenses are only activated by their legitimate owners. Unlike simple API activation, this method requires the user to log in to the WooNooW portal and explicitly authorize the activation request.

### When to use OAuth?

*   ✅ When you want strict control over license usage
*   ✅ To prevent license key sharing (key + auth required)
*   ✅ If specific user consent is legally required

---

## Authentication Flow

The flow involves three parties:
1.  **Client Application**: The software requesting activation (e.g., a customer's WordPress site)
2.  **Vendor Portal**: The WooNooW dashboard where the user manages licenses
3.  **Vendor API**: The backend handling the activation logic

<Stepper>
  <StepperItem title="Step 1: Client Requests Activation">
    The client sends a request to the activation API with `activation_mode: "oauth"`.
    
    ```bash
    POST /woonoow/v1/licenses/activate
    {
      "license_key": "XXXX-YYYY-ZZZZ-WWWW",
      "domain": "https://client-site.com",
      "activation_mode": "oauth"
    }
    ```
  </StepperItem>

  <StepperItem title="Step 2: API Request Authorization">
    The API responds with `oauth_required: true` and a redirect URL.
    
    ```json
    {
      "oauth_required": true,
      "oauth_redirect": "https://woonoow.com/my-account/license-connect/...",
      "state": "abc12345"
    }
    ```
  </StepperItem>

  <StepperItem title="Step 3: User Authorizes Request">
    The client redirects the user to the `oauth_redirect` URL. The user logs in and sees a confirmation screen:
    
    > **Authorize this Request?**
    > Site: https://client-site.com
    > License: XXXX-YYYY-ZZZZ-WWWW
    
    Once confirmed, the vendor generates a temporary **activation token**.
  </StepperItem>
  
  <StepperItem title="Step 4: Token Exchange">
    The user is redirected back to the client site with the token. The client exchanges this token for the final activation.
    
    ```bash
    POST /woonoow/v1/licenses/activate
    {
      "activation_token": "temporary-token-123"
    }
    ```
  </StepperItem>
</Stepper>

---

## Implementation Guide

### 1. Handling the Redirect

When your application receives the `oauth_redirect` response, you must open this URL in the user's browser.

<Note type="note" title="Security Check">
  Always verify the `state` parameter when the user returns to your application to prevent CSRF attacks.
</Note>

### 2. Processing the Callback

Your application needs a callback route (e.g., `/admin.php?page=my-plugin&action=callback`). This URL must be provided in the initial `return_url` parameter.

The callback will receive:
*   `activation_token`: The token needed to complete activation
*   `license_key`: The license key being activated
*   `nonce`: Random standard nonce for verification

### 3. Completing Activation

Once you have the `activation_token`, compare the `state` (if you stored it) and make the final request.

```javascript
const response = await fetch('https://api.woonoow.com/woonoow/v1/licenses/activate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        license_key: licenseKey,
        activation_token: urlParams.get('activation_token')
    })
});

const data = await response.json();

if (data.success) {
    console.log('License Activated!', data);
}
```