160 lines
4.4 KiB
Markdown
160 lines
4.4 KiB
Markdown
# 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 |
|