Organisations

Make a new HMAC key for the HCP Terraform run task

The old key stops working at once, until HCP Terraform's run task is given the new one.

POST/orgs/{org}/hcp-terraform/run-task/rotate

TL;DR

Question	Answer
What does it do?	Make a new HMAC key for the HCP Terraform run task.
What does it take?	`org` in the path.
What does it return?	Status 200 with a body of type `RunTaskWithKey`.
What can go wrong?	`401` not signed in; `403` the plan has no run task (plan.run_task_not_included), a member may not (orgs.forbidden), or the request came from an origin that may not make changes; `404` no such organisation, the caller is not a member of it, or the run task is off (run_task.not_found); `429` too many requests; `503` the server has no KEY_ENCRYPTION_SECRET, or the HMAC key can no longer be opened (run_task.unavailable); organisations are not set up on this server. Every failure uses the one error envelope.

The old key stops working at once, until HCP Terraform's run task is given the new one. The owner and an admin, on Pro and Enterprise.

Field	Type	Required	Description
`org`	`string`	yes	The organisation's id or its slug.

Status	Meaning	Body
200	The run task, with its new HMAC key.	`RunTaskWithKey`
401	Not signed in.	`ErrorResponse`
403	The plan has no run task (plan.run_task_not_included), a member may not (orgs.forbidden), or the request came from an origin that may not make changes.	`ErrorResponse`
404	No such organisation, the caller is not a member of it, or the run task is off (run_task.not_found).	`ErrorResponse`
429	Too many requests.	`ErrorResponse`
503	The server has no KEY_ENCRYPTION_SECRET, or the HMAC key can no longer be opened (run_task.unavailable); organisations are not set up on this server.	`ErrorResponse`

A 200 answer has the type RunTaskWithKey.

Field	Type	Required	Description
`active`	`boolean`	yes	Whether the owner's plan includes the run task (Pro and Enterprise). While it does not, each run is reported as passed with a sentence, and nothing is drawn.
`plan`	`"free" \| "pro" \| "enterprise"`	yes
`enabled`	`boolean`	yes	Whether the run task is on.
`endpoint`	`string \| null`	yes	The endpoint URL to give HCP Terraform, by the organisation id. Null on a server with no `API_URL`.
`keyLast4`	`string \| null`	yes	The HMAC key's last four characters, or null while the run task is off.
`failOnError`	`boolean`	yes	True when a run Plotwork cannot draw or keep is reported as failed. False (the default) reports it as passed, with a sentence.
`enabledAt`	`integer \| null`	yes	When it was turned on, in milliseconds since the epoch.
`enabledBy`	`object \| null`	yes	Who turned it on, or null when that account is gone.
`enabledBy.id`	`string`	yes
`enabledBy.email`	`string`	yes
`lastRunAt`	`integer \| null`	yes	When HCP Terraform last called it for a run, in milliseconds since the epoch, or null for never.
`lastStatus`	`"passed" \| "failed" \| null`	yes	The status sent back to the last run.
`hmacKey`	`string`	yes	The HMAC key to give HCP Terraform. Shown by this answer only; keep it out of logs and files. 64 hex characters.

Doc	Why
API reference	Every endpoint, and the error envelope
Schemas	Every request and response type
Tool reference	The operations as callable tools