Introduction - envlink

Everything envctl and the console do goes through one HTTPS API. You can call it directly from scripts and your own tools.

https://envlink-api.projectinwork.com

Authentication

Send a CLI token, or an organization API key, as a bearer token:

curl -H "Authorization: Bearer $ENVLINK_TOKEN" https://envlink-api.projectinwork.com/v1/environments

CLI tokens belong to a person and act as them. Create one in the console under Settings → CLI tokens, or with POST /v1/tokens.
API keys belong to the organization. Admins create them with POST /v1/keys.

A token is shown once; the API keeps only its hash. Repeated failed attempts from one address are refused with 429 for a minute.

Requests and responses

Bodies are JSON. Lists come back wrapped in an object, such as {"environments": [...]}, so fields can be added without breaking you. Times are RFC 3339 in UTC, and durations are strings like 30m or 6h.

Errors

Errors carry a message, and often a machine-readable code:

{ "error": "this organization may run 10 environments of this kind at once; delete one first", "code": "quota" }

Status	Meaning
`400`	The body or query isn’t what the endpoint takes
`401`	No token, or one that isn’t valid
`403`	The token can’t do this, such as a non-admin managing keys
`404`	It doesn’t exist in your organization
`410`	It existed but is gone, such as an expired artifact
`422`	The request is well-formed but not acceptable: an unknown template, a bad label, a share the template doesn’t have
`429`	Too many failed attempts, or a quota (`code: quota`)
`502`, `503`	A dependency, such as the queue or object storage, didn’t answer; retry

The flow envctl follows

POST /v1/sandboxes registers your machine and returns a single-use tailnet key.
POST /v1/environments leases an environment and returns it, with your sandbox’s new configuration.
GET /v1/environments/{id} until state is ready.
DELETE /v1/environments/{id} when you’re done.