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

Go to https://developer.waveapps.com
Sign in with your Wave account (or create one at waveapps.com)
You'll land on the Wave Developer Portal

Step 2: Register a New Application

In the Developer Portal, click "Create an Application" (or navigate to My Applications → New Application)
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
Click Save / Create
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

You'll be redirected to a Wave login page
Sign in with your Wave account
Select the business you want to connect
Click Authorize
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):

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:

{
  "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:

# Wave Finance
WAVE_ACCESS_TOKEN=eyJhbGc...

Then rebuild and restart the Wave MCP service:

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:

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:

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:

{
  "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

4.4 KiB Raw Blame History Unescape Escape