Remove mcp-gateway/wave-mcp/WAVE_API_SETUP.md
This commit is contained in:
parent
eeddd70efa
commit
675a3368c1
1 changed files with 0 additions and 160 deletions
|
|
@ -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 |
|
|
||||||
Loading…
Reference in a new issue