Add wave-mcp/WAVE_API_SETUP.md

wave-mcp/WAVE_API_SETUP.md

@@ -0,0 +1,160 @@
+# How to Get a Wave Finance API Access Token
+
+Wave uses **OAuth 2.0** for API authentication. Follow these steps to register your application and obtain an access token.
+
+---
+
+## Step 1: Create a Wave Developer Account
+
+1. Go to [https://developer.waveapps.com](https://developer.waveapps.com)
+2. Sign in with your Wave account (or create one at [waveapps.com](https://www.waveapps.com))
+3. You'll land on the Wave Developer Portal
+
+---
+
+## Step 2: Register a New Application
+
+1. In the Developer Portal, click **"Create an Application"** (or navigate to My Applications → New Application)
+2. Fill in the application details:
+   - **Name**: e.g. `My MCP Integration`
+   - **Description**: Brief description of your use case
+   - **Redirect URI**: For local/personal use, you can use `http://localhost:8080/callback`
+3. Click **Save** / **Create**
+4. Wave will display your:
+   - **Client ID** — public identifier for your app
+   - **Client Secret** — keep this private!
+
+---
+
+## Step 3: Authorize Your Wave Business
+
+Wave requires you to grant your application access to a specific Wave business. This is done via the OAuth 2.0 Authorization Code flow.
+
+### 3a. Build the Authorization URL
+
+Open this URL in your browser (replace `YOUR_CLIENT_ID` and `YOUR_REDIRECT_URI`):
+
+```
+https://api.waveapps.com/oauth2/authorize/?client_id=YOUR_CLIENT_ID&response_type=code&scope=account:*%20business:read%20business:write&redirect_uri=YOUR_REDIRECT_URI
+```
+
+**Recommended scopes:**
+| Scope | Purpose |
+|-------|---------|
+| `account:*` | Full account/user access |
+| `business:read` | Read businesses, customers, invoices |
+| `business:write` | Create/update customers, products, invoices |
+
+### 3b. Approve the Authorization
+
+1. You'll be redirected to a Wave login page
+2. Sign in with your Wave account
+3. Select the **business** you want to connect
+4. Click **Authorize**
+5. Wave redirects you back to your redirect URI with a `?code=XXXX` parameter in the URL
+
+**Copy the `code` value from the URL.** It expires in ~60 seconds.
+
+---
+
+## Step 4: Exchange the Code for an Access Token
+
+Run this `curl` command in your terminal (replace the placeholder values):
+
+```bash
+curl -X POST "https://api.waveapps.com/oauth2/token/" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "client_id=YOUR_CLIENT_ID" \
+  -d "client_secret=YOUR_CLIENT_SECRET" \
+  -d "grant_type=authorization_code" \
+  -d "code=YOUR_AUTHORIZATION_CODE" \
+  -d "redirect_uri=YOUR_REDIRECT_URI"
+```
+
+**Response:**
+```json
+{
+  "access_token": "eyJhbGc...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "refresh_token": "def502...",
+  "scope": "account:* business:read business:write"
+}
+```
+
+---
+
+## Step 5: Configure the MCP Server
+
+Add your access token to the `.env` file in the `mcp-gateway` directory:
+
+```env
+# Wave Finance
+WAVE_ACCESS_TOKEN=eyJhbGc...
+```
+
+Then rebuild and restart the Wave MCP service:
+
+```bash
+docker compose build wave-mcp
+docker compose up -d wave-mcp
+```
+
+---
+
+## Step 6: Refresh Your Token (When It Expires)
+
+Access tokens expire after 1 hour. Use the refresh token to get a new one:
+
+```bash
+curl -X POST "https://api.waveapps.com/oauth2/token/" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "client_id=YOUR_CLIENT_ID" \
+  -d "client_secret=YOUR_CLIENT_SECRET" \
+  -d "grant_type=refresh_token" \
+  -d "refresh_token=YOUR_REFRESH_TOKEN"
+```
+
+> ⚠️ **Important**: Each refresh invalidates the previous refresh token. Store the new `refresh_token` from the response.
+
+---
+
+## Verify It Works
+
+Test the token with a quick API call:
+
+```bash
+curl -X POST "https://gql.waveapps.com/graphql/public" \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "query { user { id defaultEmail } }"}'
+```
+
+Expected response:
+```json
+{
+  "data": {
+    "user": {
+      "id": "QnVzaW5lc3...",
+      "defaultEmail": "you@example.com"
+    }
+  }
+}
+```
+
+---
+
+## Requirements
+
+> **Note**: The Wave API requires an active **Wave Pro** or **Wave Advisor** subscription on the business you're connecting. Free Wave accounts cannot use the API.
+
+---
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `401 Unauthorized` | Invalid or expired token | Refresh or re-authorize |
+| `403 Forbidden` | No active Pro subscription | Upgrade the Wave business |
+| `invalid_grant` | Authorization code expired | Re-authorize (Step 3–4) |
+| `invalid_client` | Wrong client ID/secret | Double-check credentials |