//Platform Admin API

Platform Admin API

Platform admin is a credential-based super-role that governs the ButtrBase instance itself. It is not a user account — it is a dedicated app credential with role: platform_admin that issues JWTs carrying platform_admin: true.

Credential Issuance

Bootstrap (first credential)

On a fresh deployment, issue the first platform admin credential via the CLI:

~~~bash buttrbase platform-admin init ~~~

Output:

~~~ Platform admin credential created. Client ID: bb_live_cid_platform_... Client Secret: bb_live_sk_... ← printed once, store immediately

Authenticate: POST /api/auth/token with these credentials. ~~~

Issue Additional Credentials

Once you hold a platform admin token you can issue further credentials via the API. This lets you create per-operator or per-CI-pipeline credentials without sharing the bootstrap secret.

~~~http POST /api/platform/credentials Authorization: Bearer Content-Type: application/json

{ "label": "ops-team-alice" } ~~~

~~~jsonc // 201 Created { "credential_id": "crd_01abc...", "label": "ops-team-alice", "client_id": "bb_live_cid_platform_...", "client_secret": "bb_live_sk_..." // returned once } ~~~

List Credentials

~~~http GET /api/platform/credentials Authorization: Bearer ~~~

Revoke a Credential

~~~http DELETE /api/platform/credentials/:credential_id Authorization: Bearer ~~~

Revocation is immediate. Any token issued from this credential cannot be refreshed, and new authentication attempts will fail.

---

App Governance

List All Apps (across all orgs)

~~~http GET /api/platform/apps Authorization: Bearer ~~~

Approve or Reject a Publication

~~~http PATCH /api/platform/apps/:app_id/status Authorization: Bearer Content-Type: application/json

{ "status": "published", "note": "Reviewed and approved." } // or "rejected" | "archived" ~~~

---

Install Oversight

~~~http GET /api/platform/installs POST /api/platform/installs/:install_id/suspend POST /api/platform/installs/:install_id/resume ~~~

---

Vendor Configuration

Platform-level secrets for cloud marketplace connectors. Values are write-only — the API accepts them but never returns them in responses.

~~~http PUT /api/platform/config/aws-marketplace Content-Type: application/json

{ "sns_topic_arn": "arn:aws:sns:us-east-1:123456789:aws-marketplace-subscriptions", "region": "us-east-1", "metering_enabled": true } ~~~

~~~http PUT /api/platform/config/azure-marketplace { "fulfillment_api_key": "...", "webhook_secret": "..." } ~~~

~~~http PUT /api/platform/config/gcp-marketplace { "pubsub_subscription": "projects/my-project/subscriptions/marketplace-sub", "project_id": "my-project" } ~~~

---

Security Notes

  • Store platform admin credentials in a secrets manager (HashiCorp Vault, AWS Secrets Manager, etc.) — never in environment variables on shared machines.
  • Issue one credential per operator or pipeline. Revoke immediately when a team member leaves.
  • Platform admin tokens are short-lived (15 minutes). Use the refresh flow for long-running operations.
  • The /platform-admin UI path is gated by the platform_admin: true JWT claim — it is not accessible to regular org admins or app admins.