Introduction

Call envlink’s API over HTTPS: authentication, errors, and the endpoints envctl itself uses.

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

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