> ## Documentation Index
> Fetch the complete documentation index at: https://koreai-ai-for-work-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace and Team Settings

Configure workspace structure, roles, member access, security policies, encryption keys, and environment variables.

The **Workspace and Team** settings are your control center for access, security, and runtime configuration. From here you manage who can do what, how data is protected, and what values agents use at runtime.

* **Navigation**: Settings > Team
* **Required role**: Owner or Admin

***

## Workspace Structure

The Agent Platform organizes resources across three levels. You don't need all three - start with a workspace, add projects as your work grows, and only set up an organization if you need to manage multiple workspaces together.

| Level            | Description                                                                                                                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace**    | Your team's dedicated environment. Contains all agents, models, connectors, secrets, and members. Each workspace is fully isolated - data in one workspace is never accessible from another. |
| **Project**      | A group of related agents and resources for a specific use case, inside a workspace. Projects inherit the workspace's AI model configuration but can override model tier assignments.        |
| **Organization** | Optional. Sits above workspaces for shared billing and governance across multiple teams. A single-workspace setup doesn't need this.                                                         |

**What the workspace controls:**

* Who has access and what they can do (team membership and roles).
* Which AI models and providers are available (LLM policies, token budgets, rate limits).
* Which features are unlocked (based on your plan tier).

**What projects add:**

* Project members are drawn from workspace members and carry project-specific roles.
* Environment variables and secrets can be scoped per project and per environment (development, staging, production).

***

## Roles and Permissions

The platform uses hierarchical role-based access control (RBAC). Each role inherits all permissions from the roles below it.

### Workspace Roles

| Role     | Description                                           | Key Permissions                                                                          |
| -------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Owner    | Full control. One owner per workspace.                | Transfer ownership, delete workspace, manage billing, all admin operations.              |
| Admin    | Manages team members, models, and workspace settings. | Invite/remove members, configure models, manage secrets and connectors, view audit logs. |
| Operator | Manages agent deployments and monitors production.    | Deploy agents, view analytics, manage environment variables, view sessions.              |
| Member   | Builds and tests agents within assigned projects.     | Create/edit agents, run tests, manage project-level resources.                           |
| Viewer   | Read-only access to workspace resources.              | View agents, project configurations, and analytics dashboards.                           |

### Project Roles

| Role      | Description                                                        | Key Permissions                                                       |
| --------- | ------------------------------------------------------------------ | --------------------------------------------------------------------- |
| Admin     | Full control over the project's resources and settings.            | Manage all project resources, configure settings, oversee operations. |
| Developer | Creates and modifies agents, tools, workflows, and project assets. | Build and update agents, tools, workflows, and assets.                |
| Tester    | Reads project resources, runs simulations and evaluations.         | Access project resources, execute tests, validate agent behavior.     |
| Viewer    | Read-only access to the project.                                   | View project resources and configurations.                            |

**How workspace and project roles interact:**

* Workspace Owners and Admins have workspace-wide authority and can administer all projects without explicit project membership.
* Non-admin workspace members need explicit project membership for project-scoped access.
* When a workspace member creates a project, they automatically become that project's Admin and can add other workspace members from **Settings > Members**.

***

## Managing Members

Only workspace Owners and Admins can manage team membership.

### View Current Members

Go to **Settings > Team > Members**. The list shows name and email, workspace role, status (active, suspended, locked, or deactivated), and date joined.

### Invite a Member

1. Click **Invite member**.
2. Enter the invitee's email address.
3. Select a role: Admin, Operator, Member, or Viewer.
4. Click **Send invite**.

The invitee receives an email with a unique link that includes the workspace name and their assigned role. Invitations expire after 7 days and are cleaned up automatically.

**Manage pending invitations** from the **Pending Invitations** section on the Members page:

| Action | What it does                                                                 |
| ------ | ---------------------------------------------------------------------------- |
| Resend | Sends a fresh invitation email with a new token, resetting the 7-day expiry. |
| Revoke | Cancels the invitation so the link can no longer be used.                    |

<Note>If a member reports not receiving the invitation email, check the pending list and resend - you don't need to revoke first.</Note>

### Change a Member's Role

1. Find the member in the Members list.
2. Click the role dropdown next to their name.
3. Select the new role and confirm.

Role changes take effect immediately - permissions update on the member's next page load or API call.

**Platform-enforced role hierarchy rules:**

* You can't assign a role higher than your own. An Admin can't promote a member to Owner.
* Only the workspace Owner can promote a member to Admin.
* Only the workspace Owner can transfer ownership.
* You can't demote yourself - ask another Owner or Admin to change your role.

### Remove a Member

1. Find the member in the Members list.
2. Click the three-dot menu next to their row.
3. Select **Remove member** and confirm.

**What happens when a member is removed:**

* They lose access to all workspace resources immediately.
* Their project memberships within this workspace are removed.
* Resources they created (agents, knowledge bases) remain in the workspace.
* Active sessions they initiated continue running, but they can't start new ones.

<Note>Removing a member doesn't delete their Agent Platform account. They can still access other workspaces they belong to.</Note>

### Transfer Workspace Ownership

Only the current workspace Owner can transfer ownership.

1. Go to **Settings > Team > Members**.
2. Click the three-dot menu next to the target member.
3. Select **Transfer ownership** and confirm by typing the workspace name.

After the transfer, the previous Owner is demoted to Admin, and the new Owner gains full control, including the ability to delete the workspace.

***

## Role Management

Role Management lets you control what people can see and do across your workspace and projects. Roles are organized into two types:

* **Custom roles** - roles you define yourself
* **System roles** - built‑in roles that cover the most common access levels out of the box

You'll find Role Management under **Settings > Role Management**.

***

## Custom roles

Custom roles let you build access levels tailored to your team - for example, a role that can only read configuration, or one scoped to a specific set of release environments.

The **Custom roles** tab lists every custom role in your workspace, showing the role name and description, how many permissions are assigned, when it was created, and quick actions to edit or delete it.

### Creating a custom role

Click **+ Create Role** to open the creation panel, then fill in:

* **Role name** - a short, identifiable name (for example: "Analyst," "QA Lead").
* **Description** *(optional)* - context for what the role is for, useful when you have several similar roles.
* **Parent role** *(optional)* - base this role on an existing custom role to inherit its permissions. Choose **No parent role** to start from scratch. The panel shows the resulting parent chain so you can see what's being inherited before you save.

### Assigning permissions

Permissions are grouped by category. Select the specific actions this role is allowed to perform. A running count at the bottom shows how many permissions are selected.

<Note>Permissions outside your own role's grant scope are shown for visibility but can't be selected - you can't grant access you don't already have.</Note>

### Scoping release environments

If the role includes the Workbench release permission, you can also restrict *where* it's allowed to release configurations - **Development**, **Staging**, and/or **Production**. This scoping only applies to release actions; it doesn't grant production access on its own, and the underlying release permission must still be selected separately.

Click **Create** to save the role, or **Cancel** to discard it.

***

## System roles

The System roles tab lists built‑in roles, grouped by where they apply. These roles can't be edited or deleted, but you can expand any role to view the grants it includes.

Click View grants next to any role to see its full permission list.

***

## When to use Custom vs. System roles

Use a **System role** whenever one of the built-in options already matches what someone needs - they require no setup and stay current automatically. Reach for a **Custom role** when you need finer-grained control, such as read-only access to a subset of permissions, an environment-scoped release role, or a role built on top of another custom role through a parent chain.

***

## Security and Compliance

Go to **Team > Security & Compliance** to manage authentication and access controls. The page has three tabs: **MFA**, **SSO**, and **Audit Logs**.

**Required role**: Owner or Admin.

### Multi-factor Authentication (MFA)

MFA adds a verification step using a time-based one-time password (TOTP).

**Enable MFA for your account:**

Go to **Team > Security & Compliance**, click **Enable MFA**, complete the authenticator app setup, enter the verification code, and click **Verify & Enable**.

**Recovery codes** are generated during MFA setup and let you access your account if you lose your authenticator app:

* Each code can only be used once.
* Store them securely.
* Regenerating codes invalidates all previously issued codes.

**Enforce MFA for the workspace:**

From the **MFA** tab, enable **Require MFA for all members** and select a grace period.

When enforced:

* New members must configure MFA before accessing the workspace.
* Existing members must complete MFA setup within the grace period.
* Members who don't complete setup are locked out until MFA is configured.

### Single Sign-on (SSO)

SSO lets users authenticate using an external identity provider (IdP).

**Plan requirement**: Enterprise plan only.

**Generated SSO URLs**

The platform automatically generates these endpoints; there is no action to create or edit them manually. Use the URLs when configuring your identity provider's SAML/OIDC application settings. Auto-generated SSO URLs are created automatically and aren't user-configurable. Only organization owners or admins can view and use these URLs to configure SSO. Admins can select **Refresh** to reload the current URL values, but this doesn't regenerate or change them.

| SSO Protocol                    | URL                                                                 | When to use it                                                                                                                                                                                                                                         |
| ------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **SP Entity ID / Audience URI** | `https://example.com/api/sso/saml/sp/spId`                          | Enter as the **Entity ID**, **Identifier**, or **Audience URI** in the Identity Provider (IdP). It uniquely identifies the Agent Platform Service Provider (SP) and allows the IdP to validate that SAML assertions are intended for this application. |
| **SP‑initiated ACS URL**        | `https://example.com/api/sso/saml/callback`                         | Enter as the **Assertion Consumer Service (ACS) URL** or **Reply URL** in the Identity Provider (IdP) for **Service Provider (SP)‑initiated** sign‑ins.                                                                                                |
| **IdP‑initiated ACS URL**       | `https://example.com/api/sso/saml/callback`                         | Enter as the **Assertion Consumer Service (ACS) URL** in the Identity Provider (IdP) for **Identity Provider (IdP)‑initiated** sign‑ins.                                                                                                               |
| **SAML metadata URL**           | `https://example.com/api/sso/saml/metadata?metadataId=<metadataId>` | Provide this URL to the Identity Provider (IdP) to automatically import the Service Provider (SP) metadata, including the Entity ID, ACS URLs, supported bindings, and signing certificates.                                                           |
| **OIDC redirect URL**           | `https://example.com/api/sso/oidc/callback`                         | Enter as the **Redirect URI** or **Callback URL** when configuring an OpenID Connect (OIDC) identity provider.                                                                                                                                         |

**Supported protocols:**

* **SAML 2.0** - Supports Okta, Azure AD, and OneLogin.
* **OpenID Connect (OIDC)** - Supports Auth0 and Keycloak.

**Set up SAML SSO:**
Go to **Team > Security & Compliance > SSO**, select **SAML 2.0**, enter the required configuration details, and click **Save Configuration**.

**Set up OIDC SSO:**
Go to **Team > Security & Compliance > SSO**, select **OpenID Connect**, enter the required configuration details, and click **Save Configuration**.

**Domain verification:**
Use the **Domain Verification** section in the **SSO** tab to claim and verify your organization's email domain before enforcing SSO.

**Force SSO:**
Enable **Force SSO** from the **SSO** tab to require users with verified domain email addresses to authenticate through SSO.

When enabled:

* Password-based login is disabled for verified domain users.
* Users outside the verified domain are unaffected.
* Workspace Owners retain password-based login as a fallback.

**Google authentication fallback:**
Enable **Allow Google fallback** to let users sign in with Google if the configured SSO provider is unavailable.

***

## Audit Logs

Audit logs give you a tenant-scoped, filterable record of all significant workspace actions. Use them to investigate incidents, verify compliance, and review team activity.

* **Navigation**: Settings > Team > Audit Logs
* **Required role**: Owner or Admin
* **Export**: Available on Professional and Enterprise plans

Use **Refresh** to reload the log. Use **Export CSV** to download the current filtered view. Use the filter bar to narrow results by search text, date range, action type, preset, or category.

### Summary Metrics

| Metric          | Description                                |
| --------------- | ------------------------------------------ |
| Matching events | Total events matching the current filters. |
| Failed on page  | Failed events on the current page.         |
| Actors on page  | Distinct actors on the current page.       |
| Active filters  | Number of filters applied.                 |
| Last event      | Timestamp of the most recent event.        |

### Event Categories

| Category                         | Examples                                                |
| -------------------------------- | ------------------------------------------------------- |
| Auth & access                    | Login, logout, MFA, SSO, API keys.                      |
| Workspace governance             | Member invites, role changes, ownership transfers.      |
| Project, agent & workflow config | Agent creation, updates, deployments, workflow changes. |
| Tools, modules & credentials     | Tool bindings, module updates, credential changes.      |
| Data protection                  | KB updates, uploads, exports, retention events.         |
| KMS                              | Key rotations, DEK creation, provider changes.          |
| Connector configuration          | Channel connections, SDK changes.                       |
| Archives, retention & Git        | Archiving, retention policy changes, Git events.        |

### Log Table Columns

| Column    | Description                                       |
| --------- | ------------------------------------------------- |
| Timestamp | When the action occurred.                         |
| Category  | Event category.                                   |
| Action    | Specific action, for example `agent.dsl_updated`. |
| Actor     | User or system ID.                                |
| Target    | Resource affected.                                |
| Project   | Associated project.                               |
| Source    | Origin: Studio or runtime-store.                  |
| IP        | Request IP address.                               |
| Trace     | Trace ID, if available.                           |

### Retention

* Follows the workspace retention policy.
* Professional and Enterprise plans: at least 90 days.
* Contact support for extended retention.

***

## Key Management

The Key Management Service (KMS) lets you control the encryption keys used to protect sensitive workspace data. Instead of relying on platform-managed keys, you can provide your own key material from a supported cloud provider.

* **Navigation**: Settings > Team > Key Management
* **Required role**: Owner
* **Plan requirement**: Enterprise plan only

### Configuration

When **Platform Managed** is selected as the tenant-level KMS provider, the platform’s built-in encryption service is used. No tenant-specific external key connection is stored in this mode.

Encryption is governed by the platform administrator. Policies for compliance, rotation, and re-encryption are read-only here. To bring your own key, choose a different provider.

**Supported KMS providers**

| Provider              | Key type                | Region support      |
| --------------------- | ----------------------- | ------------------- |
| **AWS KMS**           | Symmetric CMK (AES-256) | All AWS regions     |
| **Azure Key Vault**   | RSA or AES keys         | All Azure regions   |
| **Azure Managed HSM** | Symmetric AES-256 keys  | All Azure regions   |
| **Google Cloud KMS**  | Symmetric AES-256 keys  | All GCP regions     |
| **External KMS**      | Any REST-compatible KMS | Self-hosted or SaaS |
| **Platform Managed**  | Platform-governed keys  | Managed by platform |

***

### Policies

| Setting              | Options                                                                                                                            | Default     |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Failure Policy**   | **Fail Closed** - all encryption/decryption stops <br /> **Graceful Degradation** - continue with cached DEKs until KMS reconnects | Fail Closed |
| **Compliance Level** | **Standard**, **PCI DSS**, **HIPAA**, **FIPS 140‑3**                                                                               | Standard    |

### Rotation and re-encryption settings

Key rotation can happen automatically (if the provider supports scheduled rotation) or manually, by creating a new key version on demand from the Encryption Keys tab.

| Setting                        | Description                                               |
| ------------------------------ | --------------------------------------------------------- |
| DEK Epoch Interval             | Frequency of DEK generation.                              |
| DEK Max Usage Count            | Maximum DEK usage before rotation.                        |
| Destroy retired DEKs           | Enables automatic destruction after the retention period. |
| KEK Rotation Period            | Frequency of KEK rotation.                                |
| Enable automatic re-encryption | Automatically queues re-encryption jobs after rotation.   |

Re-encryption also includes **Concurrency** (parallel jobs), **Batch Size** (records per batch), and **Max Retries** (retry attempts for failed jobs). Click **Save Configuration** to apply.

### Scopes

Manage different KMS providers for tenant environments, projects, and project environments.

***

## Environment Variables

Environment variables are key-value pairs scoped to a project and environment. At runtime, agents resolve `{{env.KEY}}` placeholders in tool configs and parameters to the matching value.

* **Navigation**: Settings > Team > Env Variables
* **Required role**: Owner, Admin, or Operator

```yaml theme={null}
tools:
  - name: crm-lookup
    config:
      base_url: '{{env.CRM_API_URL}}'
      timeout: '{{env.CRM_TIMEOUT_MS}}'
```

### Variable Types

| Type                 | Syntax           | Visibility                                  | Scope                                 | Use For                                              |
| -------------------- | ---------------- | ------------------------------------------- | ------------------------------------- | ---------------------------------------------------- |
| Environment Variable | `{{env.KEY}}`    | Visible to Operators; can be marked secret. | Per project, per environment.         | Non-sensitive config: URLs, feature flags, timeouts. |
| Secret               | `{{secret.KEY}}` | Hidden after creation, always secret.       | Per workspace or project.             | API keys, passwords, tokens.                         |
| Config Variable      | `{{config.KEY}}` | Plaintext, resolved at compile time.        | Per project (not environment-scoped). | Project-wide constants.                              |

### Environment Tabs

The page shows four tabs: **Global**, **Dev**, **Staging**, and **Production**. Each tab shows its variable count.

<Note>Global variables are available in all environments. An environment-specific variable with the same key takes priority over the global variable.</Note>

**Toolbar actions**: Filter keys, Refresh, Diff, Namespaces, All Variables, Export, Import, Add Variable.

### Add a Variable

1. Go to **Settings > Team > Env Variables**.
2. Select the target project from the dropdown.
3. Select the target environment tab.
4. Click **Add Variable**.
5. Enter a **Key** (use `UPPER_SNAKE_CASE`), **Value**, and optional **Description**.
6. Check **Mark as secret** if the value is sensitive.
7. Click **Create**.

<Note>Variables created on the **Global** tab are available in all environments unless overridden by an environment-specific variable with the same key.</Note>

### Edit and Delete Variables

* **Edit**: Click **Edit** to update a variable's value or description. Changes apply immediately.
* **Delete**: Click the **delete icon** and confirm.

<Note>Deleting a variable referenced in an agent definition causes runtime errors. Check all references before deleting.</Note>

### Export Variables

1. Select the environment tab.
2. Click **Export**.
3. Choose format: **JSON** (array) or **.env** (file format).
4. Click **Copy to Clipboard** or **Download**.

### Import Variables

1. Select the environment tab.

2. Click **Import**.

3. Paste JSON in this format:

   ```json theme={null}
   [
     {"key": "API_KEY", "value": "sk-xxx", "isSecret": true},
     {"key": "DB_URL", "value": "postgres://..."}
   ]
   ```

4. Check **Overwrite existing variables** to replace matching keys.

5. Click **Import**.

Variables not in the import file remain unchanged.

**Replicate variables across projects:**
Environment variables are project-scoped. To replicate them, use Export/Import with the same JSON file. For values shared across all projects, use workspace-level secrets.

***