Vallic Cloud docs

API

Tokens for scripts and pipelines, what they can reach, and the endpoints they call.

Everything a pipeline usually needs — deploying, setting a variable, adding a domain, taking a backup — can be done over HTTP with a personal access token instead of the console.

#Issuing a token

Your account → Access tokens → Issue a token. It asks three things:

Field Why
What is it for Only you see it. It is how you tell which token to revoke when something is compromised
Team The token reaches this team and nothing else, whatever else you are a member of
Expires 7, 30 or 90 days

The token is shown once. Only a digest of it is kept, so it cannot be shown again or recovered — if you lose it, revoke it and issue another.

There is no token that never expires. A token lives in CI settings, in a colleague's shell history, in a laptop that was sold; 90 days is the most any of them stays good for after it was forgotten. You are emailed from 14 days before one expires, and weekly after that.

Revoke is on the token's row. Revoked and expired tokens stay in the list, so you can see what existed and when it was last used.

#What a token can do

Exactly what you can do in that team, and no more. A token is you, narrowed to one team: your role decides what it may touch, every rule that applies to you in the console applies to it, and if your role changes, so does the token. Leaving the team leaves the token with nothing.

There are no scopes. A token cannot be limited to reading, or to one project. If a pipeline should only ever deploy, give it a token belonging to someone whose role is only Developer — a person, or an account made for the purpose.

One thing a token can never do: restore a backup over a protected production environment. That asks for your password again, and a token has no password to give. A pipeline that could replace your live database is a pipeline that could be made to.

#Calling the API

curl https://console.vallic.com/api/vc/v1/environments \
  -H "Authorization: Bearer vcp_…"

JSON in and out. Every token starts vcp_, so one committed by mistake is easy to search for.

Endpoints under /api/vc/v1
You GET /me, GET /teams
Listings GET /projects, /environments, /environments/{id}, /servers
Deploying GET /projects/{id}/releases (?branch= for one branch); POST /environments/{id}/deploy, /redeploy, /rollback
Following GET /tasks, /tasks/{id}, /tasks/{id}/log
Variables GET, POST, DELETE on /environments/{id}/variables and /projects/{id}/variables
Logs GET /environments/{id}/logs: where the environment's request and error logs go — the project's destination by kind and name, whether it can send, how many days each machine keeps its own copy. Vallic Cloud does not keep the logs, so there is nothing to tail here
Resources GET /environments/{id}/resources?window= 1h, 24h, 7d, 30d or 90d: CPU, memory and disk, oldest first, averaged into at most 500 points; step says how many seconds each covers. Kept three months
Domains GET, POST on /environments/{id}/domains; POST /domains/{id}/verify; DELETE /domains/{id}
Environments POST /projects/{id}/environments; PATCH, DELETE on /environments/{id}
Services GET /environments/{id}/services
Checking a manifest POST /validate, POST /environments/{id}/validate
Backups GET, POST on /environments/{id}/backups; POST …/backups/{snapshot}/download, …/restore

A few things worth knowing before you script against them:

  • Deploys are refused, not queued, while another is running on the same environment — you get a 409. Wait for the task and try again. See Deployments.
  • Deploy, redeploy and rollback return a task. Poll /tasks/{id} to learn how it ended, and read /tasks/{id}/log for what it printed.
  • rollback deploys the release that was running before the last successful deployment. It is code only; see going back.
  • Adding a domain takes the hostname and nothing else. Making a domain canonical and declaring a CDN in front of it are done in the console. See Domains.
  • Verification is throttled to twelve checks an hour per domain; past that you get a 429.

#How often you can call it

Two limits, and only one of them is about how busy you are.

Six hundred requests a minute per token. Past that you get a 429 and should wait and repeat the request unchanged. It is a ceiling for a loop that has lost its sleep, not a budget to plan against — a pipeline doing real work will not come near it. The count is per token, not per person or per team, so a runaway script cannot lock your colleagues out, and whoever has to revoke it can still sign in.

If you are polling a task to see how a deploy ended, poll it every few seconds rather than as fast as the loop will go. Nothing goes faster for being asked more often.

Repeatedly presenting a credential that does not work gets your address refused with a 429 for a while, whatever token you try next. A token is a bearer credential — whoever holds the string is you — so guessing has to cost something. Calling an endpoint with no Authorization header at all does not count against this: that is a 401 and nothing more, so a forgotten header cannot lock out an office that shares one address.

Presenting a token that worked clears the count, so an occasional typo in a pipeline costs you nothing once the right one goes through.

Next