Control-plane API

Everything the S3 endpoint deliberately does not do: creating buckets, minting credentials, setting CORS rules.

Two APIs, two jobs. The S3 endpoint moves objects and is what your application talks to. The control plane — documented here — manages the things around them. It is a plain JSON API at prod.api.popcloud.ca.

This page is generated from the service’s own OpenAPI schema, so it cannot drift from the running API. 46 endpoints, in 6 groups.

Authenticating

Log in, keep the access token for the session, and send it as a bearer token. It is short-lived; a refresh cookie is set alongside it and POST /v1/auth/refresh issues the next one.

Get a token
TOKEN=$(curl -fsS -X POST https://prod.api.popcloud.ca/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"…"}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["access_token"])')

curl -fsS https://prod.api.popcloud.ca/v1/buckets -H "Authorization: Bearer $TOKEN"

Your PCAK storage credentials do not work here — they authenticate to the S3 endpoint and carry no control-plane authority. For automation that matters:

Friction

The control-plane API has no machine token

You’ll see
There is no API key to give a CI job or a Terraform provider that needs to create a bucket, mint a credential, or set CORS rules.
Why
The control plane authenticates people: an access token from `POST /v1/auth/login` plus a refresh cookie. Storage credentials (PCAK…) authenticate against the S3 endpoint only — they carry no control-plane authority.
Instead
For automation, log in from the job with a dedicated user's credentials, hold the access token for the run, and refresh if the run outlives it. Do not embed a human's long-lived session in shared CI. Bucket and credential creation is otherwise a one-time setup step you can do in the dashboard.

Collections & schema

  • Postman collection — imports into Insomnia too. Set baseUrl and accessToken and go.
  • .http file — for the VS Code REST Client and JetBrains HTTP client.
  • OpenAPI schema — generate a typed client in your language.

Authentication

The control plane authenticates people, not machines: an access token plus a rotating refresh cookie. There is no API key — see the limitations page.

Your account

Who the current token belongs to, and their organisation.

Organisation

Organisation-level settings and members.

Credentials

Create, scope, rotate and revoke the PCAK credentials your applications sign with. The secret is returned exactly once.

Buckets, objects & CORS

Bucket lifecycle (which the S3 API deliberately does not offer), CORS rules for browser uploads, and server-side presigning.

System

Health and version.