Developers
Server-to-server API
Connect your own systems to Purple Grain with an API key — an OAuth client credential that acts for your account or your organisation without a person signing in. Create keys under Settings → API keys (organisation keys live on the Organisation page; you need edit rights there).
1. Get an access token
Exchange your key at the token endpoint using the OAuth 2.0 client_credentials grant. The secret is shown once at creation — if you lose it, rotate the key.
curl -s https://api.purplegrain.com/oauth/token \
-d grant_type=client_credentials \
-d client_id=YOUR_CLIENT_ID \
-d client_secret=YOUR_CLIENT_SECRET \
-d scope="public read write"The response contains access_token (Bearer) and expires_in. Mint a fresh token whenever the old one expires — tokens are cheap; secrets are precious.
Prefer not to handle the secret at all? Create a long-lived access token directly from Settings → API keys (30/90/365 days or non-expiring). The token string is shown once at creation and can be revoked there any time — note that rotating the key's secret does not revoke tokens minted this way.
2. Call the API
curl -s https://api.purplegrain.com/api/v1/clients \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json"Every endpoint is documented in the API reference. Requests accept application/json (flat) or application/vnd.api+json (JSON:API).
What a key can do
| Scope | Grants |
|---|---|
| public read | Read your owner's data (clients, jobs, services, farms…) |
| public read write | Read plus create and edit your owner's data |
Keys are strictly bound to their owner: an organisation key reaches only that organisation's data; a personal key only yours — no membership delegation, private reads included. Keys top out at edit-level authority: they can never delete the organisation, transfer ownership, remove an account, or manage API keys (keys can't mint keys).
Rotation & revocation
- Rotate regenerates the secret. The old secret stops working at the token endpoint immediately; access tokens already issued live until they expire.
- Delete removes the key and kills every access token it ever issued — integrations using it break immediately.
Errors
| Status | Meaning |
|---|---|
| 401 invalid_client / invalid_token | Bad or rotated secret, or an expired/revoked token — mint a new token |
| 403 forbidden | Outside your key's reach: another owner's data, a destroy-level operation, or a write with a read-only key |
| 422 unprocessable_entity | Validation failed — the error body says which field |
Building an AI-agent integration instead? Point your agent at the MCP server — per-user OAuth, no key management at all.