Windpaint
Overview

Authentication

Every request takes an API key as a bearer token; the key's role decides which endpoints it can call.

Authenticate by sending an API key in the Authorization header:

curl
curl https://api.windpaint.ai/v1/projects \
  -H "Authorization: Bearer $WINDPAINT_API_KEY"
Authorizationstringrequired

Bearer followed by your API key. Keys look like aak_ plus 48 hex characters.

Create keys in the dashboard under Settings → API Keys or with POST /v1/api-keys. The full lifecycle (scoping, rotation, revocation) is in API keys.

A key acts in its creator’s organization. It has its creator’s permissions, or those of the role it’s bound to with role_id. List the roles you can bind, with their ids, with GET /v1/roles. There’s no header to switch organizations; each user belongs to one.

Permissions

Each endpoint requires one permission. A key passes if its role has it.

PermissionEndpointsowneradminmemberread_only
generation:readGET /v1/generation/*, GET /v1/workflows/*, GET /v1/activities, POST /v1/generation/estimate, POST /v1/workflows/{slug}/estimate✓✓✓✓
generation:writeSubmits, uploads, cancels, workflow runs, deleting assets✓✓✓
projects:readGET /v1/projects, GET /v1/projects/{id}✓✓✓✓
projects:writeCreate, update and archive projects✓✓
billing:readGET /v1/billing/*, including GET /v1/billing/limits✓✓✓✓
billing:writePUT /v1/billing/settings, POST /v1/billing/topups✓✓
api_keys:readGET /v1/api-keys, GET /v1/api-keys/{id}✓✓✓✓
api_keys:createPOST /v1/api-keys, PATCH /v1/api-keys/{id}✓✓
api_keys:revokeDELETE /v1/api-keys/{id}✓✓
roles:readGET /v1/roles/{id}, GET /v1/roles/{id}/users✓✓✓
orgs:readGET /v1/account/storage✓✓✓✓
orgs:updatePATCH /v1/account/storage✓✓
webhooks:readGET /v1/webhooks, GET /v1/webhooks/{id}, GET /v1/webhooks/events, GET /v1/webhooks/jobs/deliveries✓✓✓
webhooks:createPOST /v1/webhooks✓✓
webhooks:updatePATCH /v1/webhooks/{id}, POST /v1/webhooks/{id}/test, GET /v1/webhooks/jobs/secret, POST /v1/webhooks/jobs/secret/rotate✓✓
webhooks:deleteDELETE /v1/webhooks/{id}✓✓

GET /v1/roles needs no permission; any valid key can list the roles. GET /v1/openapi.json and GET /v1/errors are public and need no key. Each endpoint page names its permission. Roles are described in Organizations and projects.

Authentication failures

Authentication and permission failures don’t use the standard error envelope. They return a flat body with a code you can branch on:

401
{
  "status": false,
  "error": "Unauthorized",
  "code": "auth.invalid_token",
  "message": "The token is invalid or has expired.",
  "request_id": "59630881.7c2e4a"
}
StatuscodeCause
401auth.unauthenticatedNo Authorization header.
401auth.invalid_tokenA key that doesn’t exist, a revoked, paused or expired key, or a key whose creator was removed from the organization.
401auth.account_disabledThe account behind the key is disabled.
401auth.account_pending_approvalThe account is still waiting for approval.
403auth.missing_scopeThe key is valid but its role lacks the endpoint’s permission. The message names the permission.
403auth.forbiddenThe key isn’t allowed to do this for another reason.

request_id is included when it’s available. auth.invalid_token doesn’t say which cause applies; to tell an expired key from a revoked one, look the key up in the dashboard.

Some 403s come from inside an endpoint rather than the permission check, for example binding a key to a role broader than your own. Those use the standard envelope with code auth.forbidden:

{
  "error": {
    "code": "auth.forbidden",
    "message": "You cannot grant a role with more permissions than your own.",
    "request_id": "59630881.7c2e4a"
  }
}

Handle both shapes: if error is a string, it’s an auth failure and the code is the top-level code; if it’s an object, read error.code. See Errors.

Examples

A member-scoped key generating an image works:

curl -X POST https://api.windpaint.ai/v1/generation/capabilities/image.generate \
  -H "Authorization: Bearer $WINDPAINT_MEMBER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a lighthouse at dusk"}'
# 202 {"status": "queued", ...}

The same key creating a project is refused:

curl -X POST https://api.windpaint.ai/v1/projects \
  -H "Authorization: Bearer $WINDPAINT_MEMBER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Campaign Q4"}'
# 403 {"status": false, "error": "Forbidden", "code": "auth.missing_scope", "message": "Missing scope projects:write.", ...}

A revoked key is refused everywhere:

curl https://api.windpaint.ai/v1/projects \
  -H "Authorization: Bearer aak_revoked..."
# 401 {"status": false, "error": "Unauthorized", "code": "auth.invalid_token", ...}

Keeping keys out of clients

API keys carry your organization’s credits. Use them only from servers, CI and your own machine. There are no publishable or browser-safe keys; if a browser or mobile app needs generated media, call Windpaint from your backend and hand the client a signed asset URL from GET /v1/generation/assets/{id}/url.