---
title: Administer the platform
canonical: "https://agentbarn.dev/guides/observe-and-govern/platform-administration"
pubDate: "2026-08-29T00:00:00.000Z"
updatedDate: "2026-09-28T09:19:49.000Z"
author: Agent Barn
description: "Administer Agent Barn from Platform View: global users and invitations, Organization oversight, Platform Privilege, statistics, Event Deliveries, and Platform Templates."
tags: [Observe and govern, How-to, Platform Administrators and self-hosted platform operators, reporting date range, direction, shared view, historical activity, Platform Administrator, Platform View, users, Organizations, Platform Privilege, statistics, Event Deliveries, Platform Templates]
categories: [Guides, Observe and govern]
---

-   Platform View
-   Oversight
-   15 minutes

Platform View is the installation-administration area of Agent Barn. It lets a Platform Administrator manage platform resources and review the supported oversight information across Organizations.

This access does not automatically make you a member of each Organization. To change an Organization's settings or operate its Agents, you must join that Organization and have the permissions required for the action.

## Overview

A Platform Administrator can inspect explicitly allowlisted oversight data. Platform Privilege does not make the administrator an Organization Owner, does not add every Organization to the Organization switcher, and does not authorize Organization-scoped API routes.

After completing this guide, you will be able to:

-   Enter and leave Platform View
-   Interpret platform inventory and activity statistics
-   Create pending users with an initial Organization
-   Resend pending invitations
-   Review Organizations, Owners, Creators, and Memberships
-   Grant and revoke Platform Privilege safely
-   Investigate Event Delivery failures
-   Manage global Platform Template versions
-   Manage global Platform Skills and Skill Versions
-   Recognize administration capabilities that are not implemented yet

## Platform View boundary

Platform View and Organization View answer different questions.

| Platform View | Organization View |
| --- | --- |
| Global, outside any Active Organization | Scoped to one Active Organization |
| Requires Platform Privilege | Requires a real Organization Membership |
| Lists all platform users | Manages the selected Organization’s Members |
| Lists allowlisted Organization identity | Manages Organization-owned resources |
| Shows bounded cross-Organization statistics | Shows Agents and resources accessible in that Organization |
| Monitors global Event Deliveries | Reviews tenant Activity, Logs, and Costs through Organization Permissions |
| Authors global Platform Templates | Manages Organization Templates and Agent pins |
| Manages globally visible Platform Skills | Reads Platform Skills and may fork them into Organization or Agent-owned lineages |
| Does not expose tenant configuration | Can expose configuration when the Membership and Permissions allow it |

**Platform View → allowlisted oversight projections**

├── User identity
├── Organization identity
├── Membership relationships
├── Aggregate Agent and message statistics
├── Event Delivery operational metadata
├── Platform Templates
└── Platform Skills

**Organization View → Organization-owned resources through Membership**

├── Agents
├── Templates and Skills
├── credentials and Secrets
├── Activity and Logs
└── Organization Costs

The two diagrams show that each view resolves through a different authority. Platform View reaches only allowlisted oversight projections: user identity, Organization identity, Membership relationships, aggregate Agent and message statistics, Event Delivery operational metadata, Platform Templates, and Platform Skills. Organization View reaches Organization-owned resources (Agents, Templates and Skills, credentials and Secrets, Activity and Logs, and Organization Costs), and only through a real Membership.

**Important**

Platform Privilege is not Organization Membership. A Platform Administrator must still be a real Member of an Organization before using its Organization View or any Organization-scoped API route.

Platform Administrators manage Platform Skills. Platform Skills are globally visible as read-only resources to Organizations, which may fork them into independently owned Organization or Agent-private lineages. Platform Privilege does not grant access to Organization-owned or Agent-private Skills.

Platform oversight does not expose:

-   Conversation or message content
-   Tool inputs or results
-   Agent Logs
-   Prompts and rendered configuration
-   Agent Secrets
-   Shared Credential contents
-   Raw runtime Telemetry
-   Tenant configuration payloads

Platform View uses dedicated, allowlisted read models rather than reusing tenant data-transfer objects.

## Available administration surfaces

Platform View provides six primary navigation areas. All six are global; none resolves or requires an Active Organization.

### Overview

Review current Organization and Agent inventory, and period-scoped activity.

### Users

Search global accounts, create pending users, resend invitations, and administer Platform Privilege.

### Organizations

Search Organizations and inspect Owner, Creator, and Membership identity.

### Event Deliveries

Inspect the internal delivery pipeline and diagnose handler failures.

### Templates

Author and publish global Platform Template versions.

### Skills

Create, publish, version, rename, and safely remove global Platform Skills.

## Before you begin

Confirm that:

-   You are signed in with a normal Agent Barn user session
-   Your account has Platform Privilege
-   At least one Platform Administrator will remain after any privilege change
-   Email delivery is configured if you intend to invite users
-   The Event Delivery worker and Redis are running if you intend to inspect delivery health
-   You understand that Platform View is not an Organization impersonation mechanism

In a new self-hosted installation, Agent Barn creates the bootstrap Platform Administrator from `PLATFORM_ADMIN_CREDENTIALS` when no Platform Administrator exists.

Use the in-product Platform Privilege workflow for additional administrators. Do not share the bootstrap account or its password.

## Open Platform View

1.  Sign in to Agent Barn.
2.  Open your profile menu.
3.  Find the **Platform** section.
4.  Select **Platform view**.

The route changes to:

```
/dashboard/platform
```

The top navigation changes to **Overview**, **Users**, **Organizations**, **Event Deliveries**, **Templates**, and **Skills**.

Platform View does not establish an Active Organization. The Organization switcher may still list Organizations where you hold a real Membership, but that Membership state is separate from the Platform View route.

To return to Organization View, select an Organization where you are a Member.

If the profile menu contains no **Platform** section, the signed-in account does not have Platform Privilege. Platform routes require an authenticated user session belonging to a user with Platform Privilege: API-key, service, runtime, and other non-user credential classes cannot exercise Platform Administrator authority.

## Review platform overview

The Platform landing page begins with point-in-time inventory.

| Inventory card | Meaning |
| --- | --- |
| Organizations | Current number of Organizations across the platform |
| Agents | Current number of non-deleted Agents matching the applicable Agent filters |
| Running | Agents whose last recorded status is RUNNING |
| Stopped | Agents whose last recorded status is STOPPED |
| Errored | Agents whose last recorded status is ERROR |

The Agent status cards form a current inventory snapshot. They do not change when you select a different activity period.

**Running is recorded state, not live liveness**

**Running** reflects the last status Agent Barn recorded. It is not a live Kubernetes readiness check. A runtime that failed without recording a lifecycle transition can still be counted as running.

The **Organizations** card is currently a global count. Selecting an Organization or messaging-app filter for the activity report does not narrow that card.

Use these cards for inventory and lifecycle trends, not as a replacement for Agent health or runtime monitoring.

## Analyze platform activity

The **Activity** section reports work observed during a selected period. Unlike the inventory cards, every value here is period-scoped.

| Activity card | Meaning |
| --- | --- |
| Messages | Canonical message rows in the selected window, with the display direction applied |
| Received | Inbound messages in the selected period |
| Sent | Canonical outbound rows in the window; not provider-delivery receipts |
| Active agents | Distinct Agents with messages or Tool Calls in the window, deduplicated; direction does not narrow this count |

Messages over time includes inbound/outbound counts and zero-valued empty buckets. Agents over time shows historical existing/created inventory and per-bucket active Agents.

### Choose the reporting date range

The Activity panel uses an explicit date range. Its first-load default covers today and the previous 29 days in the viewer's local timezone. The picker accepts a range of up to 366 days. Choose the start and end dates directly; the former reporting-period preset menu is no longer part of this interface.

The dates are sent as absolute timestamps and chart buckets are expressed in UTC. Around a timezone boundary, a UTC bucket label can fall on an adjacent calendar date. The API still accepts its reporting-period presets independently of the interface and defaults to the previous 30 days when no range or period is supplied.

### Filter and share the view

Filter by Organization and messaging app: Slack, Teams, Telegram, or Discord. Choose **All messages**, **Received only**, or **Sent only** to change the message cards and message series. Agent ID and creator ID remain API filters rather than controls in this panel. Email and Web Chat are not additional choices in this interface's app selector.

The date range, Organization, app, and direction are stored in the page URL. Copying the URL shares that selected view with another authorized Platform Administrator. The shared range is fixed; it does not advance as time passes. Sharing a URL does not grant Platform access.

Direction filters change the displayed message counts and series. They do not change **Active agents**, which combines message and Tool Call activity. The direction choice is applied to the returned message data in the interface; it is not a new API query parameter.

Initiated outbound messages are recorded when Communications accepts them, so they can appear in Sent before provider delivery succeeds. Inspect Communication diagnostics for delivery confirmation or failure. Do not interpret Sent as a count of answered inbound deliveries only, or assume proactive output has no stored message row.

An app-filtered message belongs to its own Connection's platform. An Agent connected to Slack and Telegram does not have each message counted under both. Tool Calls do not carry a Connection, so app-filtered Tool Call activity uses the Agent's Connections. Historical aggregates include retired Connections; current inventory uses active Connection relationships. Deleting an Agent must not erase its earlier activity from historical interpretation.

### Interpret Active Agents

An Agent is active when Agent Barn observes at least one inbound message, outbound message, or Tool Call during the period. Agents are deduplicated within the period and within each chart bucket.

Tool Calls matter here because scheduled or proactive Agent work may never produce an outbound chat message.

**Note**

Activity is a lower bound on runtime availability. A running but idle Agent produces no telemetry, and is therefore not counted as active.

### Understand time buckets

Agent Barn selects a bucket size from the requested span:

| Requested span | Automatic granularity |
| --- | --- |
| Up to 2 hours | Minute |
| Up to 3 days | Hour |
| Up to 90 days | Day |
| More than 90 days | Week |

Buckets are UTC instants. The interface builds the selected date range from the viewer’s local timezone and sends them as absolute instants, so near local midnight a chart label can fall on an adjacent UTC date even when the totals are correct.

Requests that would produce more than 5,000 buckets are rejected. Shorten the range, or request a coarser granularity.

## Manage users and invitations

Select **Users** to open the global account list. The page displays each user’s full name, email address, Platform Administrator status, creation time, and email-verification state. Organization Memberships appear on the user detail page.

### Create a user

1.  Select **Create user**.
2.  Enter the user’s email address.
3.  Optionally enter a provisional full name.
4.  Optionally enter the initial Organization name.
5.  Select **Create and invite**.
6.  Copy the invitation link if email delivery is unavailable.
7.  Send the link only through an approved secure channel.

Agent Barn atomically creates:

```
Pending User
├── Initial Organization
├── Owner Membership
└── One-time set-password invitation
```

The user chooses their own password. This is not a password-setting workflow; the Platform Administrator never creates or learns the password.

If no Organization name is supplied, Agent Barn derives one from the full name or email identity. Organization names are display labels and do not need to be globally unique.

**Security**

Treat the invitation link as a temporary credential. Do not place it in public chat, tickets, logs, screenshots, or documentation.

### Resend an invitation

1.  Find the unverified user in the list, or open their detail page.
2.  Select **Resend invitation**.
3.  Copy the new invitation link if necessary.
4.  Ask the user to discard any older link.

Resending rotates the invitation token, so previous invitation links stop working. An already-active user cannot be reinvited through this action.

### Current limitations

Platform user administration does not currently provide administrator-selected passwords, platform-level password reset, user account deletion, or account impersonation.

A Platform landing-card description may still mention password resets or account removal. Those workflows are not implemented, and must not be treated as available.

## Review Organizations

Select **Organizations** to search the global Organization catalogue. Each card shows the Organization name, description, Organization ID, Owner name and email, and creation date.

Organization names are not globally unique. Use the Organization ID, the Owner, and the immutable Creator identity to tell two Organizations apart.

### Inspect Organization detail

Open an Organization to review its name and description, the current Owner, the immutable Creator identity, the creation date, the member count, and Membership names, emails, roles, and pending state.

The Owner and the Creator can be different people. Ownership can be transferred, while Creator identity remains the historical creation identity.

Platform Organization detail is an allowlisted oversight projection. It does not expose allowed model configuration, Agents or Agent configuration, Templates and Skills, Shared Credentials, Agent Secrets, messages or Tool Calls, Logs, or Organization Costs.

Viewing an Organization in Platform View does not grant Membership, and does not add the Organization to the Organization switcher. To administer Organization-owned resources, obtain a real Membership and use Organization View.

### Platform Organization operations

Platform Administrators can configure per-Organization monthly LLM spend limits and budget alerts. When set, limits map to LiteLLM teams to enforce spend ceilings across all Agent virtual keys within that Organization.

Platform View cannot create a standalone Organization, rename one, modify its description or model allowlist, change Membership roles, remove Members, transfer ownership, delete the Organization, or suspend and reactivate it.

New Organizations are created either through user onboarding or through authenticated user self-service. See [Manage organizations and members](/guides/observe-and-govern/organizations-and-members).

## Manage Platform Privilege

Platform Privilege grants access to the global Platform View routes and operations.

### Grant privilege

1.  Open **Users**.
2.  Find the target user.
3.  Select **Grant Platform Admin**.
4.  Enter a specific operational reason.
5.  Select **Grant privilege**.

### Revoke privilege

1.  Find an existing Platform Administrator.
2.  Select **Revoke Platform Admin**.
3.  Enter the reason.
4.  Select **Revoke privilege**.

The reason must contain between 1 and 1,000 characters after surrounding whitespace is trimmed. Use a reason such as:

```
On-call platform operations responsibility for Q3
```

Do not use:

```
Requested
```

Every successful change updates the user’s Platform Privilege, emits a Platform-scoped Domain Event, and creates a durable Security Audit Record through the audit projection.

### Protected cases

Agent Barn rejects:

-   Revoking your own Platform Privilege
-   Revoking the final Platform Administrator
-   Granting privilege to an existing Platform Administrator
-   Revoking privilege from a user who does not have it
-   An empty reason
-   A reason longer than 1,000 characters

Privilege changes take effect for the target user’s subsequent requests.

**Security**

Keep at least two independently controlled Platform Administrator accounts for operational recovery. Grant Platform Privilege only to users who need global oversight, Platform Template authoring, or Platform Skill management.

Never place passwords, API keys, tokens, invitation links, or any other secret in a privilege reason; the reason is stored in a durable audit record.

## Monitor Event Deliveries

Select **Event Deliveries** to open the read-only Event Delivery Monitor.

Event Deliveries represent handler work created for internal Domain Events. They are not runtime telemetry, public webhooks, or the Security Audit Record explorer.

### Delivery lifecycle

1.  PENDING
2.  ENQUEUED
3.  PROCESSING

A claimed delivery then reaches one of two terminal states:

-   SUCCEEDED The handler completed successfully
-   DEAD\_LETTERED The delivery reached a terminal failure

The lifecycle runs PENDING, then ENQUEUED, then PROCESSING. From PROCESSING a delivery ends in either SUCCEEDED or DEAD\_LETTERED.

| Status | Meaning |
| --- | --- |
| `PENDING` | The delivery exists in PostgreSQL but is not known to be queued |
| `ENQUEUED` | The worker message was published |
| `PROCESSING` | A worker claimed the delivery |
| `SUCCEEDED` | The handler completed successfully |
| `DEAD_LETTERED` | The delivery reached a terminal failure |

### Read the summary

The summary cards show a count for every status, a stale count for the active states, an unknown-age count, the age of the oldest active delivery, and dead-lettered terminal failures. Select a summary card to filter by that status.

### Filter deliveries

The monitor supports search by delivery or Event ID; search by Organization, event name, or handler prefix; and filters for status, event type, Organization, and creation date range, with newest-first or oldest-first ordering.

Expand a row to inspect safe operational metadata: delivery and Event IDs, event name and schema version, handler name, Organization identity where applicable, status and attempt count, created, enqueued, claimed, and completed timestamps, the dead-letter reason, a bounded and redacted last error, and curated Actor or Subject display strings where available.

The monitor never exposes raw Event Payloads, credentials, Agent Secrets, message content, tool data, or raw Actor and Subject envelopes.

### Refresh and current limits

Select **Refresh** to fetch current data. The page does not poll automatically.

**Note**

The monitor is read-only. It does not currently provide manual retry, replay, republish, or status-mutation actions. Automatic reconciliation repairs eligible active deliveries according to the worker configuration.

A dead-lettered delivery requires investigation of its handler, event contract, configuration, or dependent service. It is not automatically republished.

## Manage Platform Templates

Select **Templates** to manage the global Platform Template catalogue. Platform Templates are global resources available for Organization adoption; they are not owned by an individual Organization.

A Platform Template lineage can have immutable published versions, at most one mutable Draft Template Version, required global Skills, and multiple Markdown prompt artifacts.

### Create a new lineage

1.  Select **New Template**.
2.  Enter the Template metadata.
3.  Edit the Markdown artifacts.
4.  Select the required global Skills.
5.  Save the draft.
6.  Review every artifact.
7.  Publish the draft.

The system derives the Template key. Do not invent or edit it manually.

### Update an existing lineage

1.  Open a Platform Template.
2.  Select **Start draft** or **Continue editing draft**.
3.  Edit the draft.
4.  Save without publishing as often as necessary.
5.  Publish when the version is ready.

Publishing creates the next immutable version and clears the draft.

### Restore an older version

1.  Select the historical published version.
2.  Start a Template Restore from that version.
3.  Review the resulting draft.
4.  Publish the draft.

Publishing the restore creates a new version. It never modifies the historical version, and it never moves an active-version pointer backward.

**Important**

Publishing a Platform Template does not automatically update existing Organization Templates or Agent pins. Organizations must apply the available Template Update, and Agents stay on their pinned versions until explicitly changed.

Review [Work with templates](/guides/templates-and-skills/templates) before publishing global Template changes.

## Manage Platform Skills

Select **Skills** to manage globally visible Platform Skills. Organizations see published Platform Skills as read-only resources and may fork them into independently owned Organization or Agent-private lineages.

### Create and publish a Platform Skill

1.  Select **New Skill** to create a custom Platform Skill lineage with one unpublished draft and no published Skill Version.
2.  Add exactly one root `SKILL.md` file and any additional UTF-8 files using paths relative to the Skill root.
3.  Set the draft description and required provider requirements, then review the complete bundle.
4.  Publish the draft to create the next immutable Skill Version.

Every lineage has at most one mutable draft. Publishing copies that draft into the next immutable Skill Version and clears the draft. Starting another draft seeds it from the latest published version.

### Change a Platform Skill safely

Draft changes may include files, description, and provider requirements. Renaming changes only the lineage name; content and metadata remain draft-gated. Publishing a newer Skill Version does not move existing Agent pins or change exact Template or Override requirements.

### Respect deletion boundaries

-   An individual Skill Version cannot be deleted when it is the last published version.
-   A Skill Version cannot be deleted while an Agent pin, Template or Override requirement, draft, or fork source references it.
-   A complete custom Platform Skill lineage can be deleted only when no Agent, Template, Override, draft, or fork-source reference depends on it.
-   Built-in `aai_cli` Platform Skill lineages cannot be deleted.

Platform Skills have no upstream source-update workflow because Platform is the top ownership scope. Review [Work with Skills](/guides/templates-and-skills/skills) for the shared lifecycle and scoped fork model.

## Platform View and deployment operations

Platform View is an in-product administration surface, independent of Kubernetes cluster administration. AAI Labs’ k3s `main` and `staging` deployments are branch-driven test environments using moving `latest` and `latest-staging` tags. Hosted public Agent Barn runs on the separate Talos cluster and deploys only a `vX.Y.Z` Git tag through its dedicated public workflow, using images from `registry.agentbarn.dev`.

Do not call the k3s `main` environment hosted public production. Kubernetes namespaces such as `agent-farm` are frozen infrastructure identifiers, not product branding. See [Self-hosting](/guides/self-hosting) and [Upgrade Agent Barn](/guides/self-hosting/upgrades) for the complete deployment procedure.

## Capabilities not yet available

The current Platform View does not yet include:

-   Asynchronous runtime cleanup controls
-   Unified Security Audit Record exploration
-   Model-usage oversight
-   Dedicated Tool Call statistics
-   Detailed per-Organization or per-Agent oversight dashboards
-   Tenant impersonation
-   Platform-level Organization mutation
-   Platform password reset
-   Platform user deletion

**Do not infer capabilities from plans**

Do not infer these capabilities from architecture plans, ADRs, database models, or placeholder navigation. Treat them as available only after their Platform API and interface workflows are implemented.

Security Audit Records already exist as durable projections for selected events, including Platform Privilege changes. What remains unavailable is the unified Platform View explorer for those records.

### Organization suspension is not available

Agent Barn does not currently provide a supported workflow for suspending or reactivating an Organization.

You will not find a working **Suspend** or **Reactivate** action in Platform View. A design document describing these actions does not mean they are available in the installed product.

Do not use database edits to simulate suspension. Pausing Agents, removing a person's membership, and deleting an Organization have different effects and should not be presented as equivalent operations.

For supported Organization and membership tasks, see [Manage organizations and members](/guides/observe-and-govern/organizations-and-members).

## Platform API

Platform routes use the `/api/v1/platform` prefix and require a Platform Administrator user session.

### Users

| Method | Endpoint | Purpose |
| --- | --- | --- |
| `GET` | `/api/v1/platform/users` | List and search global users |
| `POST` | `/api/v1/platform/users` | Create a pending user and initial Organization |
| `GET` | `/api/v1/platform/users/{user_id}` | Read allowlisted user and Membership detail |
| `POST` | `/api/v1/platform/users/{user_id}/resend-invite` | Rotate a pending user’s invitation |
| `PATCH` | `/api/v1/platform/users/{user_id}/platform-privilege` | Grant or revoke Platform Privilege |

An example privilege request:

```
PATCH /api/v1/platform/users/{user_id}/platform-privilege
Authorization: Bearer <user-access-token>
Content-Type: application/json
```

```
{
  "is_platform_admin": true,
  "reason": "Primary platform operations rotation"
}
```

### Organizations

| Method | Endpoint | Purpose |
| --- | --- | --- |
| `GET` | `/api/v1/platform/organizations` | List and search Organizations |
| `GET` | `/api/v1/platform/organizations/{organization_id}` | Read allowlisted Organization identity |
| `GET` | `/api/v1/platform/organizations/{organization_id}/members` | Read allowlisted Membership detail |

These are read-only oversight endpoints.

### Statistics

| Method | Endpoint | Purpose |
| --- | --- | --- |
| `GET` | `/api/v1/platform/stats/messages` | Read inbound, outbound, and total message statistics |
| `GET` | `/api/v1/platform/stats/agents` | Read current Agent inventory and period activity |

Common query parameters:

```
period=SEVEN_DAYS|THIRTY_DAYS|NINETY_DAYS
from_date=<ISO-8601 timestamp>
to_date=<ISO-8601 timestamp>
granularity=minute|hour|day|week
organization_id=<UUID>
agent_id=<UUID>
created_by_user_id=<UUID>
platform=slack|teams|telegram|discord
```

Supplying either `from_date` or `to_date` switches the request to a custom range. An omitted `to_date` resolves to the current time, and an omitted `from_date` uses the selected period length.

### Event Deliveries

| Method | Endpoint | Purpose |
| --- | --- | --- |
| `GET` | `/api/v1/platform/event-deliveries/summary` | Read global delivery-state counts and stale-state information |
| `GET` | `/api/v1/platform/event-deliveries/event-types` | List registered event types that have handlers |
| `GET` | `/api/v1/platform/event-deliveries` | Search and page through Event Deliveries |

### Platform Templates

| Method | Endpoint | Purpose |
| --- | --- | --- |
| `GET` | `/api/v1/platform/templates` | List Platform Template lineages |
| `POST` | `/api/v1/platform/templates` | Create a new lineage draft |
| `GET` | `/api/v1/platform/templates/{template_key}` | Read the latest published version |
| `GET` | `/api/v1/platform/templates/{template_key}/versions` | List published versions |
| `GET` | `/api/v1/platform/templates/{template_key}/draft` | Read the current draft |
| `POST` | `/api/v1/platform/templates/{template_key}/draft` | Start a draft, optionally from a historical version |
| `PATCH` | `/api/v1/platform/templates/{template_key}/draft` | Save draft changes |
| `DELETE` | `/api/v1/platform/templates/{template_key}/draft` | Discard the draft |
| `POST` | `/api/v1/platform/templates/{template_key}/draft/publish` | Publish the next immutable version |

### Platform Skills

| Method | Endpoint | Purpose |
| --- | --- | --- |
| `GET` | `/api/v1/platform/skills` | List global Platform Skill lineages |
| `POST` | `/api/v1/platform/skills` | Create a Platform Skill draft |
| `PATCH` | `/api/v1/platform/skills/{skill_id}` | Rename a lineage |
| `DELETE` | `/api/v1/platform/skills/{skill_id}` | Delete an unused custom lineage |
| `GET` | `/api/v1/platform/skills/{skill_id}/files` | Read the latest published files |
| `GET` | `/api/v1/platform/skills/{skill_id}/versions` | List immutable Skill Versions |
| `GET` | `/api/v1/platform/skills/{skill_id}/versions/{version}` | Read one Skill Version |
| `DELETE` | `/api/v1/platform/skills/{skill_id}/versions/{version}` | Delete an unreferenced non-final version |
| `GET` | `/api/v1/platform/skills/{skill_id}/draft` | Read the mutable draft |
| `POST` | `/api/v1/platform/skills/{skill_id}/draft` | Start a draft from the latest version |
| `PATCH` | `/api/v1/platform/skills/{skill_id}/draft` | Save files and staged metadata |
| `DELETE` | `/api/v1/platform/skills/{skill_id}/draft` | Discard the draft |
| `POST` | `/api/v1/platform/skills/{skill_id}/draft/publish` | Publish the next immutable Skill Version |

A user without Platform Privilege receives `403 Forbidden`. Missing or invalid authentication returns `401 Unauthorized`. Platform routes also reject non-user credential classes, even when the credential identifies a Platform Administrator account.

## Security considerations

Platform Privilege can expose cross-Organization identity and operational metadata. Treat it as highly privileged access.

Follow these practices:

-   Maintain at least two Platform Administrator accounts
-   Use separate named accounts rather than sharing the bootstrap account
-   Review Platform Privilege periodically
-   Require meaningful reasons for grants and revocations
-   Never place credentials or Secrets in privilege reasons
-   Deliver invitation links only through approved secure channels
-   Do not use Platform View as a substitute for Organization Membership
-   Do not copy tenant data into platform tooling to bypass the allowlisted boundary
-   Investigate stale and dead-lettered Event Deliveries without circulating bounded errors more widely than necessary
-   Review Platform Template drafts carefully, because new Organizations may adopt published versions
-   Preserve published Template history instead of trying to mutate or replace it
-   Review Platform Skill files and provider requirements before publication; publishing makes the Skill globally available, while existing consumers remain pinned to exact Skill Versions
-   Use provider billing systems, not Platform statistics, as the financial authority

Platform oversight fields are explicit security decisions. A field becoming available in an Organization API does not automatically make it appropriate for Platform View.

## Troubleshooting

| Symptom | Likely cause | Resolution |
| --- | --- | --- |
| Platform is missing from the profile menu | The signed-in account does not have Platform Privilege | Ask another Platform Administrator to grant it. |
| Platform View reports that Platform admin access is required | The current user is not a Platform Administrator | Verify the signed-in account and its privilege state. |
| A Platform API returns 403 with a service token | Platform authority requires a user-session credential | Authenticate with a Platform Administrator user session instead. |
| An Organization is absent from the Organization switcher | Platform Privilege does not create Membership | Obtain a real Membership if Organization View is required. |
| An Organization is visible in Platform View but cannot be opened in Organization View | The administrator is not a Member of that Organization | Use the Platform detail projection for oversight, or request Membership. |
| Two Organizations have the same name | Organization names are non-unique display labels | Compare the Organization ID, the Owner, and the immutable Creator. |
| Creating a user returns 409 Conflict | The email already belongs to an account | Open the existing user instead of creating a new one. |
| Resending an invitation returns 409 Conflict | The account is already active | Ask the user to sign in, or to use the supported password-recovery flow. |
| An older invitation link no longer works | A newer invitation rotated the token | Use the most recently generated invitation. |
| A privilege change cannot be saved | The reason is empty or exceeds the allowed length | Enter a trimmed reason of 1 to 1,000 characters. |
| Self-revocation fails | A Platform Administrator cannot revoke their own privilege | Ask another Platform Administrator to perform the change. |
| Revoking another administrator fails | They are the final Platform Administrator, or the requested state is unchanged | Grant another administrator first, or cancel the no-op change. |
| Running Agents exceed Active Agents | Running is recorded state, while Active requires observed telemetry | Treat activity as a lower bound on runtime liveness. |
| Activity dates appear shifted by a day | Date ranges use local calendar boundaries while charts use UTC buckets | Compare the absolute range against the UTC bucket timestamps. |
| Statistics return 422 Unprocessable Entity | The range is invalid, or would exceed 5,000 buckets | Correct the dates, shorten the range, or request a coarser granularity. |
| Active agents did not change when I selected Sent only | Direction changes the message display | Active agents still combines all message and Tool Call activity. |
| Sent increased before a message arrived | Canonical outbound recording is separate from provider delivery | Inspect the Delivery journal. |
| A removed Agent still appears in historical activity | Historical aggregates retain past Connection relationships and messages | Use current inventory for non-deleted Agent counts. |
| The date range did not advance after opening a shared link | Shared URLs preserve absolute dates | Choose a new range to review later activity. |
| A delivery remains Pending, Enqueued, or Processing | The transport, worker, handler, or reconciliation path may be unhealthy | Review the stale age, worker health, Redis, and reconciler execution. |
| A delivery is Dead-lettered | Automatic retries ended, or a terminal validation or configuration error occurred | Inspect its reason and bounded error, then repair the handler or dependency. |
| There is no retry control for a failed delivery | The Event Delivery Monitor is currently read-only | Repair the underlying system and rely on the supported worker and reconciliation process. |
| A published Platform Template did not update an Agent | Existing Organization Templates and Agent pins remain unchanged | Apply the available Template Update, or explicitly repin the Agent. |
| Skills is missing from Platform View | The signed-in user lacks Platform Privilege | Ask a Platform Administrator to grant the privilege, then sign in again. |
| A new Platform Skill is not visible to Organizations | The lineage has a draft but no published Skill Version | Review the bundle and publish the draft before expecting read-only visibility. |
| Deleting a Skill Version returns a conflict | It is the last version or is referenced by an Agent, Template, Override, draft, or fork source | Keep the protected version or remove every dependency before retrying. |
| Deleting a Platform Skill lineage is blocked | Consumers or provenance references still depend on the custom lineage | Remove Agent, Template, Override, draft, and fork-source references first; built-in aai\_cli lineages remain protected. |
| A newly published Skill Version did not update an Agent | Agent Skill pins are immutable exact-version selections | Explicitly repin the Agent after reviewing the new Skill Version. |
| Security Audit Records cannot be searched in Platform View | Unified audit exploration is deferred | Use supported operational evidence until the audit explorer is implemented. |

## Next steps

1.  Confirm that at least two Platform Administrator accounts remain.
2.  Review outstanding pending invitations.
3.  Investigate stale or dead-lettered Event Deliveries.
4.  Review Platform Template drafts before publishing.
5.  Review Platform Skill drafts and protected references before publishing or deleting.
6.  Continue to [Self-hosting](/guides/self-hosting) for worker, Redis, database, and deployment operations.

[**Self-hosting** Worker, Redis, database, and deployment operations](/guides/self-hosting) [**Platform Administration and Oversight** The underlying authority and data-classification model](/guides/platform-administration) [**Manage organizations and members** Tenant-level Membership workflows](/guides/observe-and-govern/organizations-and-members) [**Manage roles and permissions** Platform, Organization, and Agent authority compared](/guides/observe-and-govern/roles-and-permissions)

## Platform cost reporting

Platform Administrators can use separate cross-Organization cost reporting, including unattributed spend, burn rate, available OpenRouter credit, and estimated runway. See [Review Platform costs](/guides/observe-and-govern/costs#platform-costs). This access does not grant Organization Membership.