Authentication & API keys

Every request to the GroWrk developer platform is authenticated as you. A single API key works across the REST API and the CLI, and can also authenticate MCP, so you manage one credential, not three.

• The REST API and CLI send the key in an X-API-KEY header.
• MCP clients usually connect with OAuth 2.1 (an interactive "Sign in with GroWrk" flow), but they can present the same X-API-KEY instead.

Keys are user-bound: they carry your identity and act with your role. See org reach below for exactly how far that goes.

Mint an API key

1. In the GroWrk app, open Developers → API Keys.
2. Select Create API Key and choose a company + app for the key.
3. Select the Capabilities the key should carry (see Capabilities below).
4. Copy the raw key. It starts with grk_sk_ and is shown only once. Store it somewhere safe (a secrets manager, not your source tree).

You can create multiple keys and revoke any of them at any time. Revoking a key takes effect immediately on the next request.

Capabilities

Capabilities are scopes that govern what a key can do. Select only what your integration needs:

The same scopes apply on every surface: REST, CLI, and MCP. Scope is enforced per operation: a key without mcp:orders:write can list orders but cannot place one, and the request is rejected with 403 Forbidden. (The whoami / me identity check needs no scope.)

Scopes are not hierarchical. mcp:orders:write does not imply mcp:orders:read; each capability is checked literally. A key that places orders and reads them back must carry both. This is the most common cause of an unexpected 403.

Note that reading an employee's assigned devices is an inventory capability, not an employee one: GET /v4/employees/{id}/devices requires mcp:inventory:read.

Org reach

A user-bound key acts as you. Its reach is the union of the companies you administer:

• For a company owner or admin, that means full access across every company on your account.
• For a manager or employee, the key is limited to exactly what your dashboard role can see: your teams, regions, or just your own records.

In other words, an API key never grants more than your dashboard role, but it does span all the companies that role covers. Treat a key like your password.

How credentials resolve (CLI)

When you use the CLI, it looks for a key in this order:

1. A --api-key flag on the command.
2. The GROWRK_API_KEY environment variable.
3. The active account stored in ~/.growrk/config.yml (the CLI supports multiple named accounts).

See the CLI page for growrk auth login.

Using a key

Once you have a grk_sk_ key, the same value works everywhere:

# REST: X-API-KEY header
curl https://ai.growrk.com/v4/me \
  -H "X-API-KEY: grk_sk_your_key_here"

# CLI: stored once with `growrk auth login`
growrk auth login --api-key grk_sk_your_key_here

# MCP: OAuth 2.1 is preferred, but a key works via X-API-KEY too
#   POST https://ai.growrk.com/mcp

The REST call above doubles as a health check: GET /v4/me needs no capability, so it returns who you are and which companies you can reach for any valid key.

Legacy v2 keys

Two key formats exist, and they are not interchangeable:

A GW. key will not authenticate against /v4, /mcp, or the CLI. It returns 401 with "This API key is not bound to a user". v2 keys are still issued and still valid for v2 endpoints, so holding one is not a sign that anything is wrong; you simply need to mint a grk_sk_ key for the developer platform.

The v2 API shuts down on 1 Jan 2027. See the Legacy v2 API reference for what it still covers, and Migrating from v2 to v4 for the scope mapping and reissue steps.

Next: the v4 REST API reference.