diff --git a/mcp-gateway/wave-mcp/WAVE_API_SETUP.md b/mcp-gateway/wave-mcp/WAVE_API_SETUP.md deleted file mode 100644 index 6c8208e..0000000 --- a/mcp-gateway/wave-mcp/WAVE_API_SETUP.md +++ /dev/null @@ -1,160 +0,0 @@ -# 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 |