Legacy v2 API
The v2 API will shut down on 1 Jan 2027. You will not be able to create new v2 API keys after 1 Jan 2027. Existing keys will keep working until then.
The v2 API is the previous generation of the GroWrk developer surface. It is deprecated: it still works, it is still issuing keys, and it is still the only option for a few endpoint groups, but everything it covers is moving to the v4 REST API.
If you are starting a new integration, start on v4. If you already have one, see Migrating from v2 to v4.
Base URL
https://api.growrk.com/v2
Authentication
v2 sends its key in the same X-API-KEY header v4 uses, so the header is not what distinguishes them. The key is:
| Legacy v2 | v4 | |
|---|---|---|
| Prefix | GW.… | grk_sk_… |
| Bound to | A company | A user |
| Authorizes with | Fine-grained api.* scopes, one per endpoint | Ten mcp:* capabilities, one read/write pair per domain |
| Works on | https://api.growrk.com/v2 | /v4, /mcp, and the CLI |
curl https://api.growrk.com/v2/teams \
-H "X-API-KEY: GW.your_key_here"
A request with no key, an unknown key, or a key missing the endpoint's scope returns 403 with:
{ "message": "Unauthorized" }
A v2 key will not work on v4. Sending a
GW.key to/v4,/mcpor the CLI fails with401and "This API key is not bound to a user". That is the single most common false alarm during migration: the key is valid, it is simply the wrong generation. Check the prefix before debugging anything else. There is no in-place upgrade: moving to v4 means minting a newgrk_sk_key.
Scopes
Every v2 endpoint is gated on its own scope string, selected when the key is minted. They are far more granular than v4's capabilities: around thirty of them, including separate scopes for reading, creating and updating an employee's delivery address.
Because the scopes are per-endpoint, a v2 key is only as broad as the list attached to it. This is the main thing that changes on v4, where ten capabilities cover the same ground more coarsely. See the scope mapping.
Endpoints
The published Client API covers 13 paths:
Teams
| Method | Path | Scope |
|---|---|---|
GET | /v2/teams | api.teams.getAll |
POST | /v2/teams | api.teams.create |
GET | /v2/teams/{teamId} | api.team.get |
PATCH | /v2/teams/{teamId} | api.team.update |
Employees
| Method | Path | Scope |
|---|---|---|
GET | /v2/employees | api.employees.getAll |
POST | /v2/employees | api.employees.create |
GET | /v2/employees/{employeeId} | api.employee.get |
PATCH | /v2/employees/{employeeId} | api.employee.update |
GET | /v2/employees/{employeeId}/deliveryAddress | api.employee.deliveryAddress.get |
POST | /v2/employees/{employeeId}/deliveryAddress | api.employee.deliveryAddress.create |
PATCH | /v2/employees/{employeeId}/deliveryAddress | api.employee.deliveryAddress.update |
Orders
| Method | Path | Scope |
|---|---|---|
GET | /v2/orders | api.orders.getAll |
POST | /v2/orders/assignToEmployee/{employeeId} | api.orders.create |
POST | /v2/orders/offboarding | api.orders.create |
POST | /v2/orders/collection | api.orders.create |
POST | /v2/orders/swap | api.orders.create |
POST | /v2/orders/purchaseOrder | api.orders.create |
Note that v2 picks the order type by URL, with a different endpoint per type. v4 collapses the first four into a single POST /v4/orders with an orderType field.
Products
| Method | Path | Scope |
|---|---|---|
POST | /v2/products/uploadProducts | api.products.create |
POST | /v2/products/addPinCode | api.product.update |
Other v2 surfaces
The Client API above is the documented surface, but it is not all of v2. Catalogs have their own specification, and several groups (checkout, company preferences, recovery confirmations and the Organization API) are reachable with the appropriate api.* scopes without being part of this reference. Those groups have no v4 equivalent yet, so a key that uses them keeps working against v2 after the rest of your integration moves. Contact support if you need their contracts.
Lists return everything
v2 list endpoints return a bare JSON array with no pagination: GET /v2/employees returns every employee. v4 paginates and caps a page at 50 records.
This is the difference most likely to break a migrated client quietly, because it truncates rather than errors. If you have a v2 call that relies on getting the full set back in one request, see what changes before you move it.
After the shutdown
On 1 Jan 2027 the v2 API stops serving and new v2 keys can no longer be created. Existing keys keep working right up to that date, and nothing is switched off early, but there is no extension path, and no way to convert a GW. key into a grk_sk_ one.
Next: Migrating from v2 to v4.