# Wave OAuth Credentials Setup

## Prerequisites

- A Wave account (sign up at [waveapps.com](https://www.waveapps.com))

## Steps

1. Go to the [Wave Developer Portal](https://developer.waveapps.com/hc/en-us)
2. Go to **Manage Applications** and start a new application
3. Fill in the application details:
   - **Application Name**: Your application name (e.g., "Your Company - Unify")
   - **Redirect URI**: `https://unify.apideck.com/vault/callback`
   - **Description**: Brief description of your integration
4. Accept the terms, then create the application
5. Copy the **Client ID** and **Client Secret**

## Important Notes

- **Wave Pro or Advisors required for connecting businesses**: a business that connects to your integration needs an active Wave Pro plan or Wave Advisors subscription to authorize it. This does not apply to you as the developer while you're testing your own application against your own account: a free Wave Starter account gives you the same API access as Pro for that purpose.
- **Distribution needs Wave's approval**: registering the application and testing it against your own account is self-service. Taking the integration live for other Wave businesses is not: Wave's [Permitted Use policy](https://developer.waveapps.com/hc/en-us/articles/360020596771-Permitted-Use-Developers-and-Integrators) requires Wave's approval for any integration that isn't direct-to-your-own-business. Plan for this step before you tell customers you're ready to connect.
- Wave OAuth tokens expire and are refreshed automatically via the refresh token flow
- The redirect URI must match exactly
- For local development, register a separate app with redirect URI `https://localhost:3050/vault/callback`

## Scopes

Wave uses granular scopes in `resource:operation` format. The integration requests:

| Scope | Access |
|-------|--------|
| `account:read` | Read chart of accounts |
| `account:write` | Create/update accounts |
| `business:read` | Read business information |
| `customer:read` | Read customers |
| `customer:write` | Create/update/delete customers |
| `invoice:read` | Read invoices |
| `invoice:write` | Create/delete invoices |
| `product:read` | Read products/services |
| `product:write` | Create/update products |
| `transaction:*` | Read bank transactions (Wave has no `transaction:read`; full access is the only read-capable scope) |
| `user:read` | Read user profile |
| `vendor:read` | Read vendors/suppliers |

Wave returns a `refresh_token` automatically on the authorization-code exchange: there is no `offline_access` scope (requesting it triggers `invalid_scope`).

## FAQ and troubleshooting

**A connected business's subscription lapses.** If a connecting business's Wave Pro or Advisors subscription lapses, the next token refresh returns `403 Forbidden` and the connection stops working until the subscription is reactivated on their end.

**"Application review pending" or similar when trying to go live.** That's Wave's Permitted Use approval, not a bug in your setup. See the note above. Registration and self-testing are unaffected; only distributing to other businesses needs it.