# 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 |