> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blink.store/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2.0 Overview

> Build 'Connect with Blink' integrations that let sellers connect their Blink store in one click without copying API keys.

Blink supports the industry-standard **OAuth 2.0 Authorization Code flow** (with optional **PKCE** support). Using OAuth 2.0, third-party SaaS platforms, course hosts, automation tools, and plugins can let Blink merchants connect their store with a single click—without manually generating or pasting API keys.

<CardGroup cols={3}>
  <Card title="1. Authorize" icon="user-check">
    Redirect the seller to `/oauth/authorize` to select their store and approve your requested permissions.
  </Card>

  <Card title="2. Exchange Code" icon="key">
    Exchange the 5-minute `code` at `POST /api/oauth/token` for a store-scoped `access_token`.
  </Card>

  <Card title="3. Call Blink APIs" icon="bolt">
    Use `Authorization: Bearer <access_token>` across all `/api/v1/*` endpoints and webhooks.
  </Card>
</CardGroup>

***

## Step 1: Register Your OAuth Application

1. Log in to your Blink Dashboard and navigate to **Developer → OAuth Apps** (`https://app.blink.store/developer/oauth-apps`).
2. Click **New OAuth App** and configure:
   * **Application Name & Description**: Displayed to sellers on the consent screen.
   * **Logo & Website URL**: Your brand icon and homepage.
   * **Allowed Redirect URIs**: One or more callback URLs (e.g., `https://yourapp.com/oauth/blink/callback`). For local testing, `http://localhost:3000/callback` is also supported.
   * **Default Scopes**: The permissions your integration requires (e.g., `products:read orders:read webhooks:write`).
3. Copy your **`client_id`** (`blnk_client_...`) and save your one-time **`client_secret`** (`blnk_secret_...`).

<Tip>
  **Verified Partner Badge**: Official partner integrations can request verification from the Blink team to display a green **Verified** badge on the seller consent screen.
</Tip>

***

## Step 2: Redirect Sellers to the Consent Screen

When a user clicks **"Connect with Blink"** in your application, redirect their browser to:

```text theme={null}
https://app.blink.store/oauth/authorize
```

### Query Parameters

| Parameter | Required | Description |
| :- | :- | :- |
| `client_id` | **Yes** | Your application's Client ID (`blnk_client_...`). |
| `redirect_uri` | **Yes** | Must exactly match one of the Allowed Redirect URIs registered in your OAuth app settings. |
| `response_type` | **Yes** | Must be `code`. |
| `scope` | No | Space- or comma-separated list of scopes (e.g., `products:read orders:read webhooks:write`). If omitted, your app's configured Default Scopes are requested. |
| `state` | Recommended | An opaque random string generated by your app to prevent CSRF attacks. Blink echoes this exact value back to your `redirect_uri`. |
| `mode` | No | Pre-selects `live` or `test` mode on the consent screen (defaults to `live`; sellers can also toggle between Live and Test on the consent card). |
| `code_challenge` | No | Optional PKCE challenge (`S256` base64url-encoded SHA-256 hash or `plain`). |
| `code_challenge_method` | No | `S256` (recommended) or `plain`. |

### Example Authorization URL

```text theme={null}
https://app.blink.store/oauth/authorize?client_id=blnk_client_c35awnC5stJvE1aMvZYHMBpH&redirect_uri=https%3A%2F%2Fpartner.com%2Foauth%2Fblink%2Fcallback&response_type=code&scope=products%3Aread+orders%3Aread+webhooks%3Awrite&state=xyz987
```

### Handling the Callback

Once the seller selects their store and clicks **Authorize**, Blink redirects them back to your `redirect_uri` with a single-use authorization `code` (valid for **5 minutes**) and your `state`:

```text theme={null}
https://partner.com/oauth/blink/callback?code=blnk_code_9f8e7d6c5b4a...&state=xyz987
```

If the user clicks **Cancel**, Blink redirects with `?error=access_denied&state=xyz987`.

***

## Step 3: Exchange the Code for an Access Token

From your backend server, make a `POST` request to `https://app.blink.store/api/oauth/token` (supports both `application/json` and `application/x-www-form-urlencoded`, as well as HTTP Basic Auth):

```bash theme={null}
curl -X POST https://app.blink.store/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "blnk_client_c35awnC5stJvE1aMvZYHMBpH",
    "client_secret": "blnk_secret_Yje9xK2mPqL8vN4rT6wZ1aB3cD5eF7gH9iJ0kL",
    "code": "blnk_code_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
    "redirect_uri": "https://partner.com/oauth/blink/callback"
  }'
```

### Example Response

```json theme={null}
{
  "access_token": "blnk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "token_type": "Bearer",
  "refresh_token": "blnk_rt_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0",
  "scope": "products:read orders:read webhooks:write",
  "store": {
    "id": "54ba8e0a-ba35-4609-902e-0ec0b236ac81",
    "name": "Acme Digital Store",
    "subdomain": "acme",
    "custom_domain": null,
    "currency": "usd",
    "mode": "live"
  }
}
```

<Info>
  **Token Lifespan**: Like Shopify and Stripe Connect OAuth tokens, Blink OAuth `access_token` values **do not expire automatically**—they remain active until revoked by the partner (`POST /api/oauth/revoke`), rotated via `grant_type=refresh_token`, or revoked by the seller in their Blink Dashboard (**Developer → API Keys**).
</Info>

***

## Step 4: Calling Blink APIs & Verifying the Store

Pass the `access_token` in the `Authorization: Bearer <access_token>` header on any `/api/v1/*` request. Because each OAuth token is bound directly to the authorized store, **you do not need to pass an `x-store-id` header**.

To verify the token and retrieve the connected store's profile at any time, call [`GET /api/v1/me`](/api-reference/oauth/retrieve-connected-store):

```bash theme={null}
curl -X GET https://app.blink.store/api/v1/me \
  -H "Authorization: Bearer blnk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
```

***

## Available OAuth Scopes

Assign only the scopes your application needs. If no scopes are specified (`scope` omitted and Default Scopes left empty), full store access (`*`) is requested.

| Category | Scope | Description |
| :- | :- | :- |
| **Products** | `products:read` | View products, variants, and pricing |
| | `products:write` | Create, update, and archive products |
| **Orders** | `orders:read` | View order history, line items, and statuses |
| | `orders:write` | Create or update orders |
| **Customers** | `customers:read` | View customer profiles and purchase history |
| | `customers:write` | Create and update customer records |
| **Subscriptions** | `subscriptions:read` | View active and canceled subscriptions |
| | `subscriptions:write` | Cancel, pause, swap, or update subscriptions |
| **Webhooks** | `webhooks:read` | View configured webhook endpoints |
| | `webhooks:write` | Register and manage webhook endpoints programmatically |
| **Checkouts & Links** | `checkouts:read` / `checkouts:write` | View and create programmatic checkout sessions |
| | `checkout_links:read` / `checkout_links:write` | View, create, and update hosted checkout links |
| **Discounts** | `discounts:read` / `discounts:write` | View, create, and manage discount codes |
| **Fulfillment** | `license_keys:read` / `license_keys:write` | View, issue, validate, and revoke software license keys |
| | `files:read` / `files:write` | View and upload digital deliverables |
| **Growth** | `affiliates:read` / `affiliates:write` | View and manage affiliates and referral links |
| | `bumps:read` / `bumps:write` | View and manage checkout order bumps |
| | `abandoned_carts:read` | View cart recovery sessions |
| | `audience:read` / `audience:write` | View and manage audience subscribers and tags |
| | `geo_pricing:read` / `geo_pricing:write` | View and configure regional PPP pricing rules |
| **Metered Billing** | `meters:read` / `meters:write` | View and configure usage billing meters |
| | `usage_records:read` / `usage_records:write` | View and report customer usage events |
| **Finances** | `metrics:read`, `balances:read`, `payouts:read` | Read store analytics, balances, and payouts |
| | `refunds:read` / `refunds:write` | View and issue order refunds |
| | `disputes:read`, `subscription_invoices:read` | View disputes and recurring invoices |
| | `taxes:read` / `taxes:write` | View and configure tax settings |
| | `splits:read` / `splits:write`, `payees:read` / `payees:write` | View and manage revenue splits and payees |
| | `organizations:read` / `organizations:write` | View and manage seat-based organizations |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.