Complete OAuth 2.0 authorization at https://api.gusto.com/oauth/authorize; Gusto uses a partner model — you must apply for API access and be approved before production credentials are issued.
Exchange the authorization code for tokens at https://api.gusto.com/oauth/token; access tokens expire — store the refresh token and use POST /oauth/token with grant_type=refresh_token to renew.
Register a webhook subscription by POSTing to https://api.gusto.com/v1/webhook_subscriptions with 'url', 'subscription_types' (array of event types like 'Employee.created'), and a shared secret for HMAC verification.
Retrieve companies accessible to the token with GET /v1/me, which returns the 'roles.payroll_admin.companies' array containing company UUIDs needed for subsequent calls.
Access payroll data with GET /v1/companies/{company_id}/payrolls?processed=true — this lists processed payroll periods; append '/{payroll_id}' for line-item detail including employee pay.
Validate incoming webhooks by computing HMAC-SHA256 of the raw request body using the shared secret and comparing it to the 'X-Gusto-Signature' header value.
Known gotchas
Gusto's API is gated behind a partner program with manual approval; developer sandbox credentials are separate from production and must be requested independently — there is no self-serve production key.
Payroll read endpoints require the 'payrolls:read' scope explicitly; requesting only 'public' or 'openid' scopes at OAuth time will result in 403s on payroll endpoints even for valid tokens.
Webhook delivery is not guaranteed to be in order; Gusto may deliver events out of sequence or retry failed deliveries — always use the event timestamp and idempotency keys rather than assuming delivery order.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp