The Symphony REST API

Cirata Symphony exposes a secure REST API that includes platform functionality and endpoints for extensions. It complements the NATS messaging for clients that prefer to use a request-response method only over standard HTTPS communication.

Endpoints

NATS

The NATS endpoint for this instance of Symphony is at

nats://your-symphony-instance.com:4222

REST

The REST endpoint is at

https://your-symphony-instance.com/api/v1

Authentication

The majority of endpoints require authentication using Bearer authentication. Each request must include a security token in the Authorization header:

Authorization: Bearer <token>

The <token> is the token issued for an API Key, which specifies the particular capabilities available for a client using that token. See Account and Login for how to create API keys.

Using the cirata CLI

Many API operations are also available through the cirata command-line tool, which handles authentication automatically after cirata login. See the CLI Reference for the full command list.

Common API Endpoints

Public Endpoints (No Authentication Required)

Method	Path	Description
GET	/api/v1/ping	Connectivity test. Returns 200 OK when Symphony is running.
GET	/api/v1/health	Health check. Returns component status (NATS, messaging), version info. Returns 200 when healthy, 503 when degraded.
GET	/api/v1/ready	Readiness probe for Kubernetes and load balancers. Returns 200 when ready to serve traffic, 503 otherwise.
GET	/api/v1/symphonyinfo	Returns instance information including name, version, and NATS connection details.

Authenticated Endpoints

Method	Path	Description
GET	/api/v1/usertoken	Exchange an OIDC token for a Symphony user token.
GET	/api/v1/userinfo	Get information about the signed-in user.
GET	/api/v1/roles	Get the current user's resolved roles and effective permissions.
POST	/api/v1/keys	Create a new API key.
GET	/api/v1/keys	List all API keys for the current user.
PUT	/api/v1/key/:id	Update an existing API key.
GET	/api/v1/apikey	Exchange a bearer token for API key credentials (JWT + seed).
GET	/api/v1/extensions/all	List all registered extensions and their status.
GET	/api/v1/extensions/features	Get aggregated features from all extensions.
GET	/api/v1/extensions/bundles/active	List active UI dependency bundles for every extension the user can see. Each entry includes identifier, prefix, version, importMap, and integrity. Used by the UI loader for bundle resolution.
POST	/api/v1/extensions/:identifier/bundle/:version	Upload a bundle for the named extension registration. URL :identifier must equal the authenticated API key's identifier.
GET	/api/v1/extension/:id	Get details of a single extension.
ANY	/api/v1/extension/:id/*path	Proxy a request to an extension's service endpoint.
GET	/api/v1/openapi	Aggregated OpenAPI spec combining platform and extension endpoints.

Admin Endpoints (Require symphony-admin Role)

Method	Path	Description
GET	/api/v1/admin/roles	List all defined roles.
POST	/api/v1/admin/roles	Create a new role definition.
GET	/api/v1/admin/role/:name	Get a specific role definition.
PUT	/api/v1/admin/role/:name	Update a role definition.
DELETE	/api/v1/admin/role/:name	Delete a role definition.
GET	/api/v1/admin/assignments	List group-to-role assignments.
POST	/api/v1/admin/assignments	Create a group-to-role assignment.
DELETE	/api/v1/admin/assignment/:group	Delete a group-to-role assignment.
GET	/api/v1/admin/user/:subject/roles	Get roles for a specific user.
GET	/api/v1/admin/settings	Get platform settings (idle timeout, dependency resolution mode, CDN cache).
PUT	/api/v1/admin/settings	Update platform settings.
GET	/api/v1/admin/cdn/status	Get CDN cache runtime status (size, limits, errors).
GET	/api/v1/admin/bundles	List all uploaded extension bundles with version, active status, publish time, and size.
PUT	/api/v1/admin/bundles/:prefix/active	Promote a specific version to active for an extension prefix (rollback / staged promotion).
DELETE	/api/v1/admin/bundles/:prefix/:version	Force-delete a non-active bundle version.
POST	/api/v1/admin/licenses	Upload a vendor-issued license file.

Request and Response Examples

Get Instance Information

# Using the CLI
cirata info

# Using curl
curl https://your-symphony-instance.com/api/v1/symphonyinfo

{
  "name": "Cirata Symphony",
  "short": "Symphony",
  "nats": "wss://symphony.example.com:9222",
  "version": "1.0.0"
}

Get API Key Credentials

# Using the CLI
cirata account

# Using curl
curl -H "Authorization: Bearer <token>" https://your-symphony-instance.com/api/v1/apikey

{
  "jwt": "eyJ0eXAiOiJKV1QiLC...",
  "seed": "SUAB...",
  "id": "api_key_identifier",
  "account": "account_public_key"
}

The JWT contains the capabilities (subject permissions) associated with the API key. The seed is the private key for signing NATS connections.

Create an API Key

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Extension Key",
    "pub": {"allow": ["cirata.extensions.myext.>", "_INBOX.>"]},
    "sub": {"allow": ["cirata.extensions.myext.>", "cirata.services.>", "_INBOX.>"]}
  }' \
  https://your-symphony-instance.com/api/v1/keys

List Extensions

# Using the CLI
cirata extension list

# Using curl
curl -H "Authorization: Bearer <token>" https://your-symphony-instance.com/api/v1/extensions/all

[
  {
    "name": "Ice Flow",
    "prefix": "datamigrator",
    "description": "Data replication and migration",
    "status": "connected"
  }
]

Error Responses

All API errors return a JSON object with an error field:

{
  "error": "Unauthorized"
}

Common HTTP status codes:

Status	Meaning
200	Success
400	Bad request—invalid parameters or JSON
401	Unauthorized—missing or invalid bearer token
403	Forbidden—valid token but insufficient permissions
404	Not found—endpoint or resource does not exist
413	Request body too large—exceeds the 1 MB limit
429	Rate limited—too many requests
502	Bad gateway—extension service request failed
503	Service unavailable—returned by /health and /ready when components are degraded

Request Size Limits

All API endpoints enforce a 1 MB request body size limit. Requests exceeding this limit are rejected with a 413 Request Entity Too Large response. This protects the server from memory exhaustion.

Extension API Endpoints

Extensions that provide an OpenAPI specification automatically get their services exposed as REST endpoints under /api/v1/extension/:id/. The Swagger UI documents all available platform and extension endpoints, grouped by tag. Extension endpoints appear under headings named after each extension.

Rate Limiting

All authenticated and admin endpoints are rate-limited per IP address:

• Authentication endpoints (20 requests/minute): /api/v1/usertoken, /api/v1/keys (POST), /api/v1/key/:id (PUT)
• All other authenticated and admin endpoints (60 requests/minute): general API usage including extension queries, admin operations, and service proxy requests

Public endpoints (/ping, /health, /ready, /symphonyinfo) are not rate-limited.

Security Headers

All API responses include standard security headers:

Header	Value
X-Content-Type-Options	nosniff
X-Frame-Options	DENY
X-XSS-Protection	1; mode=block
Strict-Transport-Security	max-age=31536000; includeSubDomains
Referrer-Policy	strict-origin-when-cross-origin

See Also

• CLI Reference—Full cirata command reference
• Account and Login—Creating API keys
• Swagger API Documentation—Interactive API explorer
• Security Reference—Subject patterns and RBAC details