Organizations & Workspaces

How the Polycrate API structures resources into organizations and workspaces, including credentials, multi-tenancy and best practices.

Organizations & Workspaces

Overview

The Polycrate API uses a hierarchical model to structure resources:

graph TB
    subgraph ORG[Organization<br/>e.g. My Company or Customer ABC]
        subgraph WS1[Workspace 1 - Production]
            WS1_BLOCKS[Blocks]
            WS1_CREDS[Credentials]
            WS1_RUNS[Action Runs]
        end

        subgraph WS2[Workspace 2 - Staging]
            WS2_BLOCKS[Blocks]
            WS2_CREDS[Credentials]
            WS2_RUNS[Action Runs]
        end

        subgraph SHARED[Shared Resources]
            CONTACTS[Contacts]
            ORG_CREDS[Credentials org-level]
            MW[Maintenance Windows]
            RETENTION[Backup Retention Policies]
        end
    end

Organizations

An organization is the top level of the resource hierarchy. It typically represents:

• A company or a department
• A tenant (in MSP scenarios)
• A project or product

Creating an Organization

Organizations are created in the web interface under Administration → Organizations.

Organization Settings

Configurable at the organization level:

• Contacts: People who are notified on alerts
• Credentials: Shared credentials for all workspaces
• Backup Retention: How long backups are kept
• Default Settings: Inherited settings for new workspaces

Workspaces

A workspace corresponds to a Polycrate workspace on the CLI side. It is registered automatically when the CLI runs an action with the API enabled.

Automatic Registration

# The workspace is registered automatically in the API
polycrate run my-block install --api-enabled

On the first run:

1. The CLI checks whether the workspace exists in the API
2. If not: the workspace is created with the label polycrate.io/auto-created: true
3. The block is also created automatically if needed
4. The action run is recorded

Workspace Properties

Workspace PoP (Point of Presence)

Every workspace must be assigned to a PoP (Point of Presence). The PoP represents the geographic or logical location – e.g. a data center or a cloud region.

• Required on creation: When creating a workspace (Create and Edit), the PoP field is mandatory
• Condition-based monitoring: Workspaces without a PoP or with an archived PoP receive the conditions WORKSPACE_POP_MISSING or WORKSPACE_POP_ARCHIVED – visible in the web UI
• Usage: The PoP assignment is used, among other things, for AI Maintenance Detection, dashboard maps and regional overviews

Workspace View

In the web interface, the workspace detail page shows:

• Overview: Status, last activity, metrics
• Blocks: All blocks with versions and status
• Action Runs: History of all executions
• Alerts: Active alerts for this workspace
• Credentials: Associated secrets (encrypted)

Credentials

Credentials are encrypted access data that can be defined at different levels:

Credential Hierarchy

graph TB
    ORG_CREDS[Organization Credentials] -->|inherited by| WS_CREDS[Workspace Credentials]
    WS_CREDS -->|inherited by| BLOCK_CREDS[Block Credentials]

Credential Types

Credential Security

• All credentials are stored encrypted in the database
• Audit logging for all access
• No plaintext display in the UI (only on explicit export)
• API-key-based access for programmatic use

Multi-Tenancy

The Polycrate API supports full multi-tenancy:

Resource Isolation

• Each organization only sees its own resources
• Workspaces are strictly isolated
• No cross-organization access is possible

Permission Model

graph TB
    SUPER[Super Admin<br/>System-wide] --> ORG_ADMIN[Org Admin<br/>Organization-wide]
    ORG_ADMIN --> WS_ADMIN[Workspace Admin<br/>Workspace-specific]
    WS_ADMIN --> VIEWER[Viewer<br/>Read-only access]

SSO Integration

For enterprise environments:

• OIDC support: Keycloak, Okta, Azure AD, etc.
• Group mapping: OIDC groups → Polycrate roles
• Automatic user creation on first login
• Centralized session management

Best Practices

Organization Structure

=== "Single Company"

Organization: my-company
├── Workspace: production
├── Workspace: staging
└── Workspace: development

=== "Managed Service Provider"

Organization: customer-a
├── Workspace: customer-a-prod
└── Workspace: customer-a-staging

Organization: customer-b
├── Workspace: customer-b-prod
└── Workspace: customer-b-staging

=== "Product-based"

Organization: product-alpha
├── Workspace: alpha-prod-eu
├── Workspace: alpha-prod-us
└── Workspace: alpha-staging

Organization: product-beta
└── Workspace: beta-prod

Credential Management

1. Organization-wide credentials for shared resources (e.g. cloud providers)
2. Workspace-specific credentials for environment-specific access
3. Regular rotation via the API or web UI
4. Minimal permissions following the least-privilege principle