Platform Operations

tramai-platform is the multi-tenant, API-key-protected operational layer above the workflow server. It is for teams that need tenancy, scoped access, plugins, and audit around workflow execution.

What This Covers

Team/project scoping for workflow isolation
API key authentication with scoped authorization
Per-key token-bucket rate limiting
JDBC-backed audit logging
Plugin discovery and lifecycle management
Webhook adaptation through plugin-registered sources

When to Use It

Add tramai-platform when:

multiple teams or projects share a TramAI deployment
you need API key authentication for workflow endpoints
you need rate limiting per API key
you need audit logging for compliance
you want runtime plugin support

If you only need single-tenant workflow access, tramai-server alone is sufficient.

Minimum Setup

Dependency

implementation("dev.tramai:tramai-platform:0.3.1")
implementation("dev.tramai:tramai-server:0.3.1")

Database

The platform migration creates these tables:

platform_team
platform_project
platform_api_key
platform_audit_log
platform_plugin

Plugin Directory

tramai:
  platform:
    plugins:
      dir: ${java.io.tmpdir}/tramai-platform-plugins

Authentication Model

Platform requests use:

X-API-Key: <raw key>

Scope values:

Scope	Access
`run`	Start and resume workflows
`read`	Query runs and status
`admin`	Manage API keys, plugins, audit

admin grants every scope.

Creating an API Key

{
  "teamId": "team-a",
  "projectId": "project-a",
  "name": "ci-runner",
  "scopes": ["run", "read"],
  "burstCapacity": 20,
  "refillTokensPerSecond": 5.0
}

Current implementation:

keys are stored as BCrypt hashes
the raw key is only returned at creation time
each key belongs to exactly one team and one project
last-used timestamps are tracked
revocation is explicit

API Key Endpoints

Method	Path	Scope
`POST`	`/api-keys`	`admin`
`GET`	`/api-keys`	`admin`
`DELETE`	`/api-keys/{id}`	`admin`

Team and Project Boundary

The platform enforces workflow-run isolation by (teamId, projectId).

Important: The repository has tables for teams and projects, but there are not yet public HTTP endpoints to create them. Tenant bootstrap happens through application code, seed data, migrations, or direct repository usage.

Workflow Endpoints

Method	Path	Scope
`POST`	`/workflows/{name}/run`	`run`
`GET`	`/workflows/{name}/runs`	`read`
`GET`	`/workflows/{name}/runs/{id}`	`read`
`POST`	`/webhooks/{name}`	Webhook path (no API key)

Rate Limiting

Enforced per API key. When rejected:

status: 429 Too Many Requests
headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Audit Log

Persisted in JDBC. Stored fields:

timestamp
actor id
action
resource type
resource id
team id
metadata JSON

Query endpoint:

GET /audit-log?action=workflow.start

Note: tramai-server has a separate in-memory /audit endpoint. Do not confuse them:

tramai-server -> /audit
tramai-platform -> /audit-log

Plugin Model

Plugins are runtime JARs that implement TramaiPlugin.

Plugin Capabilities

external step executors
webhook adapters
dashboard extensions

Plugin Lifecycle

Method	Path	Scope
`GET`	`/plugins`	`admin`
`POST`	`/plugins/install`	`admin`
`POST`	`/plugins/{id}/enable`	`admin`
`POST`	`/plugins/{id}/disable`	`admin`

The plugin manager:

scans a configured directory for JARs
uses ServiceLoader for discovery
persists plugin state in JDBC
can enable or disable discovered plugins

Important: Dropping a JAR in the directory is not enough — enable/disable state is also persisted in platform_plugin.

Webhook Adapters

Platform webhooks add a source dimension:

POST /webhooks/{name}?teamId=...&projectId=...&source=demo.webhook

The webhook source id resolves through the plugin webhook adapter registry. The adapter transforms the payload into workflow initial state. The resulting run is recorded as actor webhook:{source}.

Dashboard Relationship

The dashboard (tramai-dashboard) is a separate module:

can render against server-style endpoints
the platform exposes extra admin surfaces for API keys, audit logs, and plugins
the dashboard auth bootstrap detects the platform API key authenticator and reports apikey as auth provider

Limitations

no public HTTP endpoints yet for team or project creation (bootstrap via code/seed data)
no encrypted secret storage API
no full RBAC or user management
no archival/export management
no full workflow version management APIs

Next Steps

Server — the base HTTP layer
MCP Integration — expose platform workflows as MCP tools
Custom Plugins — write your own TramaiPlugin