Skip to content

Pieces Enterprise

Fresh

Content Freshness

This content reflects the latest Pieces documentation as of May 2026.

What This Guide Covers

Pieces for Enterprise lets you deploy AI-powered development tools across your engineering organization. This walkthrough covers everything from creating your first organization to configuring SSO, managing members, and controlling settings at scale.

Follow the steps in order for a complete setup, or use the table of contents to jump to any section. Each section includes full documentation with images, step-by-step instructions, and links to related topics.

Contact Sales Supportnorth_east

02

Open the Pieces User Portal

The Pieces User Portal is your default landing page for account and organization management. Sign in to the portal to view your profile, subscription, and billing—and to create your first organization.

From the portal settings page, use the + Create Organization button in the header to start creating an organization. The next section walks through the full creation and join flow.

Portal settings view when you have no organization yet; use the header button to create one.

Open Pieces User Portalopen_in_new

03

Creating & Joining Organizations



Create a new organization to start collaborating with your team, or accept an invitation to join an existing organization. Organizations allow you to share resources, manage team-wide settings, and collaborate effectively.

Modal showing the walkthrough of creating an organization

Creating an Organization

Set up a new organization to start collaborating with your team. The creation process includes selecting a subscription plan and configuring initial settings.

1

Access Creation Flow

Click your User Profile in the top left, then click Settings and select Account. Scroll down to the Organizations & Teams section and click the + Create an organization button. Alternatively, you can access the creation flow from your Personal Workspace.

2

Authenticate

You'll be redirected to the Pieces Auth page, where you can sign in with your account credentials. If you encounter issues, you can access the login page directly at portal.pieces.app/auth/login.

3

Enter Organization Name

Enter your organization name in the provided field, then choose a name that clearly identifies your team or company.

4

Choose Number of Seats

Select the number of seats for your organization using the + and - buttons or by typing a number. The number of seats determines how many team members can be invited.

info

You can adjust this later from the billing page.

5

Select Subscription Plan

Choose your subscription plan:

  • Enterprise Seat Yearly: $275.99/seat/yr
  • Enterprise Seat Quarterly: $69.99/seat/quarter
  • Enterprise Seat Monthly: $22.99/seat/mo

6

Complete Checkout

Click Checkout to proceed to the payment screen. Complete the payment process using PayPal, G Pay, or credit card through the Paddle payment system.

7

Review Success Screen

After completing payment, you'll see a success screen and receive a confirmation email. Click the X in the top right of the success popup to proceed to the next step.

8

Invite Team Members (Optional)

You can invite team members by entering their email addresses and selecting roles (Owner, Admin, Write, or Read). Click Send Invites & Finish to complete setup, or click Skip for Now to invite members later.

warning

If you encounter a "Loading your workspace..." issue that prevents you from accessing your organization, you can resolve it by navigating to portal.pieces.app/auth/logout to forcefully sign out, then sign back in to access your workspace.

Joining an Organization

Accept an invitation to join an existing organization and start collaborating with your team.

1

Receive Invitation

You'll receive an email invitation from the organization owner or admin. The email will contain details about the organization and your assigned role.

2

Accept Invitation

Click the invitation link in the email to accept the invitation. You'll be immediately redirected to authenticate if needed.

3

Access Organization

After accepting the invitation, you can access the organization from your Personal Workspace by clicking the organization dropdown in the sidebar to select and view the organization.


Next Steps

Now that you've created or joined an organization, learn about managing organizations to explore member management, billing, and settings, or check out the Organization Home page to learn how to navigate your organization dashboard.

04

Onboarding & SSO

open_in_new

Share with your team

Send this link to new team members. It walks them through accepting their invite, installing Pieces, and signing in — no admin knowledge required.

content_copyCopy link



This guide walks admins through getting their team set up with Pieces and walks team members through accepting their invitation and installing Pieces. Share this page directly with your team to get everyone onboarded.

Setting Up Your Team

As an organization owner or admin, you'll invite team members, ensure you have enough seats, and share resources to help your team get started.

Creating Your Organization

If you haven't created your organization yet, you'll need to do that first. The process involves choosing a name, selecting seats, picking a subscription plan, and completing checkout.

1

Start the Creation Flow

Click your User Profile in the top left of Pieces Desktop, then click Settings and select Account. Scroll down to the Organizations & Teams section and click + Create an organization. You can also start directly at portal.pieces.app.

2

Configure Your Organization

Enter your organization name, choose the number of seats, and select a subscription plan (Enterprise Seat Yearly, Quarterly, or Monthly). Complete checkout to create your organization.

For the full creation walkthrough, see Creating and Joining Organizations.

Inviting Team Members

Once your organization is set up, invite your team by email. Each invited member needs an available seat in your subscription.

1

Open the Invite Modal

Click Members in the sidebar, then click the Invite people button in the top right corner.

2

Add Members and Assign Roles

Enter email addresses and select a role for each member:

  • Owner — Full control including organization deletion
  • Admin — Full access except organization deletion
  • Write — Can create and edit resources
  • Read — View-only access

3

Send Invitations

Click Send Invites & Finish to send the invitations. Each member will receive an email with instructions to join.

lightbulb

For large teams, you can bulk invite members by uploading a CSV file with the format email,role (one member per line). Click the Upload CSV option in the invite modal.

You can also share direct download links with your team so they can install Pieces before or after accepting their invitation:

  • macOS — Download for Mac
  • Windows — Download for Windows
  • Linux — Download for Linux

Alternatively, team members can download Pieces directly from the organization's Home page in the Pieces portal after they accept their invitation.

Managing Seats

Make sure you have enough seats for your team before sending invitations. You can view current seat usage on the Members page and add seats from the Billing page. See Billing for details on adjusting seat counts.

For Team Members: Getting Started

If you've received an invitation to join a Pieces organization, follow these steps to get set up.

info

Onboarding users need to sign in with the same email the invitation was sent to.

Accepting Your Invitation

1

Check Your Email

You'll receive an email invitation from your organization's admin. The email includes details about the organization and your assigned role.

2

Click the Invitation Link

Click the link in the email to accept. You'll be taken to the Pieces portal to sign in or create an account.

3

Create Your Account

If you don't already have a Pieces account, create one using the email address the invitation was sent to. If you already have an account, sign in with your existing credentials.

Installing Pieces

After accepting your invitation, you'll land on your organization's Home page in the Pieces portal. The Setup section at the top provides everything you need to get Pieces installed.

Organization Home page showing Setup section with download links and sign-in instructions

1

Download or Launch Pieces

If Pieces is already installed, click Open Pieces Desktop to launch it. If not, click Download for Mac (or your platform) to download the installer. Links for Windows and Linux are also available under Other platforms.

2

Install PiecesOS and Pieces Desktop

Run the downloaded installer, which sets up both Pieces Desktop and PiecesOS (the background service that powers Pieces). Follow the on-screen prompts to complete installation.

3

Sign In to Sync

After installation, sign in to Pieces Desktop and PiecesOS with the same email address associated with your organization. The Home page will remind you which email to use — look for the message that says "Sign in with [your-email] in Desktop & PiecesOS to stay in sync."

info

Signing in with your organization email ensures your settings, models, API keys, and features configured by your admin automatically sync to your installation.

Exploring Resources

The Resources section on the Home page provides quick links to help you get the most out of Pieces:

  • Documentation — Guides and API reference at docs.pieces.app
  • Pro tip guides — Tips and best practices for using Pieces effectively
  • Support — Get help and contact the Pieces team
  • GitHub — Explore repos and open source projects

SSO & Provisioning

Enterprise plans support Single Sign-On (SSO) and SCIM user provisioning for streamlined onboarding. SSO lets users sign in with your identity provider, and SCIM provisioning automates user lifecycle management.

Admins can configure SSO by adding a Descope Tenant ID in General Settings. For Associated Domains, add your company's email domain to enable automatic user assignment.

info

For help setting up SSO or SCIM provisioning, contact sales@pieces.app.


Next Steps

Once your team is set up, explore Organization Settings to configure features, API keys, models, and LTM sources for your entire team, or see Features for a full overview of enterprise capabilities.

05

Inviting Members



Add team members by sending invitations. You can invite one at a time, add multiple, or bulk upload via CSV. Each member needs an available seat.

Invite members modal showing email input, role selection, and CSV upload option

How to Open the Invite Modal

1

Open the Portal

Go to portal.pieces.app and sign in. Select your organization from the sidebar dropdown if needed.

2

Click Invite People

Click the Invite people button in the top right corner. The button is available from any tab (Home, Members, Models, Long Term Memory, Billing, Settings). The invite modal opens.

Understanding Member Roles

Before inviting members, understand the different roles available and what each role can do within your organization.

Member roles overview showing Owner, Admin, Write, and Read role descriptions

Each role has different permissions:

  • Owner - Full control including organization deletion
  • Admin - Full access except organization deletion
  • Write - Can create and edit resources
  • Read - View-only access

Invitation Methods

Invite team members using different methods depending on your needs and team size.

Inviting a Single Member

1

Open the Invite Modal

Go to portal.pieces.app, sign in, and select your organization. Click Invite people in the top right corner (available from any tab).

2

Enter Email Address

In the Invite Organization Members modal, enter the email address of the person you want to invite in the email input field.

3

Select Role

Click the Select a role... dropdown next to the email field and choose the appropriate role (Owner, Admin, Write, or Read).

4

Send Invitation

Click the Send Invites & Finish button (or Send Invitations if available) to send the invitation. The member will receive an email with instructions to join.

Inviting Multiple Members

1

Open the Invite Modal

Go to portal.pieces.app, sign in, and select your organization. Click Invite people in the top right corner (available from any tab).

2

Enter First Member

Enter the email address and select a role for the first member.

3

Add Another Member

Click the + Add another member link below the first member's information.

4

Enter Additional Members

Repeat the process to add email addresses and roles for each additional member you want to invite.

5

Send All Invitations

Once all members are added, click Send Invites & Finish to send invitations to all members at once.

Bulk Inviting via CSV

1

Open the Invite Modal

Go to portal.pieces.app, sign in, and select your organization. Click Invite people in the top right corner (available from any tab).

2

Prepare CSV File

Create a CSV file with the format: email,role (one member per line). For example:

john@example.com,Admin
jane@example.com,Write
bob@example.com,Read

content_copy

3

Upload CSV

In the invite modal, find the Upload CSV section. Click the Upload CSV button or drag and drop your CSV file into the upload area.

4

Review and Send

Review the imported members and their roles, then click Send Invites & Finish to send all invitations.

Understanding Seat Limitations

Your organization subscription includes a specific number of seats that determine how many active members you can have. Each active member uses one seat, and you cannot invite more members than you have available seats.

warning

You can only invite members if you have available seats in your subscription. If you see a "No seats available" warning, you'll need to upgrade your subscription or remove inactive members before inviting new ones.

Checking Seat Availability

Before inviting members, check your current seat usage:

1

Navigate to Members Tab

From your organization's Home page, click Members in the sidebar navigation.

2

View Seat Usage

At the top of the Members page, you'll see the Seat Usage card showing how many seats are used out of your total subscription (e.g., "1 of 1 seats used").

3

Upgrade if Needed

If you need more seats, navigate to the Billing tab to increase your seat count. You can also remove inactive members to free up seats.

Members tab showing seat usage card with current usage and total seats

Seat Management

Understanding how seats work helps you manage your organization effectively:

  • Seat Usage - View current seat usage in the Members tab
  • Upgrading Seats - Increase seats from the Billing tab when you need to invite more members
  • Minimum Seats - You must maintain at least one seat based on your number of active members
  • Available Seats - Available seats = Total seats - Active members

Next Steps

Now that you know how to invite members, learn about managing members to update roles and handle member-related tasks, or explore billing to manage your subscription and seat count.

06

Managing Members



The Members tab provides a comprehensive view of all organization members, seat usage, pending invitations, and member management tools. Use this section to track membership, update roles, and manage access.

Members tab showing seat usage, current members list, and pending invites

How to Get to Members

1

Open the Portal

Go to portal.pieces.app and sign in. Select your organization from the sidebar dropdown if needed.

2

Open Members

Click Members in the sidebar navigation.

Viewing Members and Seat Usage

1

Navigate to Members

From your organization's Home page, click Members in the sidebar navigation.

2

View Seat Usage

At the top of the Members page, you'll see the Seat Usage card showing how many seats are used out of your total subscription (e.g., "1 of 1 seats used") with a visual progress bar.

3

View Current Members

Scroll down to the Current Members section to see a list of all active organization members, their email addresses, and their assigned roles (Owner, Admin, Write, or Read).

Viewing Pending Invitations

Track invitations that have been sent but not yet accepted by members.

1

Open Pending Invites Tab

In the Members page, click the Pending Invites tab at the top of the page.

2

Review Pending Invitations

View all invitations that are waiting for acceptance. You'll see the email addresses and roles assigned to each pending invitation.

Managing Members

Update member roles and remove members from your organization.

Managing Member Roles

Update member roles to change their permissions and access levels within the organization.

1

Select a Member

In the Current Members list, find the member whose role you want to change. Click the vertical ellipsis icon (three dots) next to their name to open the member options menu.

2

Change Role

Select the role dropdown and choose a new role:

  • Owner: Full control including deletion rights
  • Admin: Full access except organization deletion
  • Write: Can create and edit resources
  • Read: View-only access

3

Save Changes

A save reminder appears at the bottom of the page. Click Save to apply the role change. The member's permissions will update immediately.

Removing Members

Remove members from your organization when they no longer need access.

1

Select Member to Remove

In the Current Members list, click the vertical ellipsis icon next to the member you want to remove.

2

Remove Member

Select Remove from Organization from the options menu.

3

Confirm Removal

Confirm the removal action. The member will immediately lose access to the organization and their seat will become available.

Understanding Seat Management

Seats are tied to your subscription and determine how many active members your organization can have.

Seat usage card showing current usage and total seats available

Understanding how seats work helps you manage your organization effectively:

  • Active Members - Each active member uses one seat
  • Minimum Seats - You must maintain at least one seat based on your number of active members
  • Seat Availability - Available seats = Total seats - Active members
  • Upgrading - Increase seats from the Billing tab when you need to invite more members

Next Steps

Now that you understand member management, learn about billing to manage your subscription and seat count.

07

Member Permissions



Understanding your role and permissions helps you know what you can do within your organization and what requires owner or admin access. Each role has specific capabilities and limitations.

Understanding Roles

Organizations have four main roles with different permission levels. Each role determines what you can do within the organization.

Members tab showing seat usage and member list with role indicators

The four roles are:

  • Owner - Full control including organization deletion
  • Admin - Full access except organization deletion
  • Write - Can create and edit resources
  • Read - View-only access

Role Permissions

Each role has specific capabilities and limitations that determine what you can do within an organization.

Read Role Permissions

Members with the Read role have the most limited access. They can view content but cannot create or modify anything.

What Read members CAN do:

  • View organization Home page and resources
  • View organization members list

What Read members CANNOT do:

  • Invite or manage members
  • Access billing or settings

Write Role Permissions

Members with the Write role can create and edit content but cannot manage the organization.

What Write members CAN do:

  • Everything Read members can do, plus:
  • Create and manage their own content

What Write members CANNOT do:

  • Invite or manage members
  • Change member roles
  • Access billing or settings
  • Manage organization-wide settings

Admin Role Permissions

Admins have extensive access but cannot delete the organization.

What Admins CAN do:

  • Everything Write members can do, plus:
  • Invite and manage members
  • Change member roles
  • Access billing and manage subscriptions
  • Configure organization settings
  • Manage all organization content

What Admins CANNOT do:

  • Delete the organization (reserved for Owners)

Owner Role Permissions

Owners have full control over the organization.

What Owners CAN do:

  • Everything Admins can do, plus:
  • Delete the organization
  • Full control over all organization resources

How Permissions Affect Daily Use

Your role determines what you see and can do in the organization interface:

  • Sidebar Navigation - Read and Write members see fewer options than Admins and Owners
  • Action Buttons - Some buttons (like Invite people) only appear for Admins and Owners
  • Settings Access - Only Admins and Owners can access the Settings and Billing sections
  • Content Management - Your ability to manage content depends on your role

Requesting Access Changes

If you need different permissions to perform your work:

1

Contact Owner or Admin

Contact your organization Owner or Admin to request a role change.

2

Explain Your Needs

Explain what you need to do and why you need different permissions.

3

Role Update

If appropriate, the Owner or Admin can update your role. Role changes take effect immediately and affect what you can access in the organization.


Next Steps

Now that you understand member permissions, learn about member overview to see what features are available to you, or explore managing organizations if you become an Owner or Admin.

08

Organization Home & Dashboard


Organization Home

The Home page is your central dashboard for managing your organization in the Pieces User Portal. The sidebar gives you quick access to Members, Models, Long Term Memory, Billing, and Settings.

Organization Home page with Setup, Manage, and Resources sections

How to Get to Your Organization

1

Open the Portal

Go to portal.pieces.app and sign in. Or from Pieces Desktop, click your User Profile in the top left → SettingsAccount.

2

Select Your Organization

In the sidebar, click the organization dropdown at the top (shows your org name). Select the organization you want to access.

3

View Home

The Home page shows setup instructions, management links, and resources. Use the sidebar to jump to any section.

How to Get to Each Section

Use the sidebar to reach the main organization areas:

1

Members

Click Members in the sidebar to view members, seat usage, and pending invites. Click Invite people to add new members.

2

Models

Click Models in the sidebar to configure AI models and API keys. Use the Models tab for provider toggles and allow-lists; use the API Keys tab to add credentials.

3

Long Term Memory

Click Long Term Memory in the sidebar to manage context capture, blocked applications, blocked websites, and default models.

4

Billing

Click Billing in the sidebar to view your plan, change seats, and manage billing contact. Owners and Admins only.

5

Settings

Click Settings in the sidebar to configure General (org name, contact, domains) and Features (External Cloud, Analytics). Owners and Admins only.

Setup, Manage, and Resources

The Home page body has three areas:

  • Setup — Prompts to sign in with your account email in Desktop & PiecesOS, plus buttons to open or download Pieces Desktop.
  • Manage — Cards that link directly to Members, Models, and Billing. Click a card to jump to that section.
  • Resources — Links to documentation, pro tips, support, and GitHub.

Next Steps

Invite members, configure Models and API keys, or check Settings for General and Features.

09

Managing Organizations



Organization Home

Access your organization's Home page to get set up, navigate to management tools, and find helpful resources for your team.

Organization Home page showing setup instructions, management links, and resource cards

north_east\ \ Learn More\ \ Learn how to navigate your organization Home page, access setup resources, and manage your organization.

Inviting Members

Add team members to your organization by sending invitations. You can invite members individually, add multiple members at once, or bulk upload via CSV.

Invite members modal showing email input, role selection, and CSV upload option

north_east\ \ Learn More\ \ Discover how to invite team members, assign roles, and use bulk invitation methods.

Managing Members

View and manage all organization members, track seat usage, handle pending invitations, and update member roles and permissions.

Members tab showing seat usage, current members list, and pending invites

north_east\ \ Learn More\ \ Learn how to manage member roles, view seat usage, and handle member-related tasks.

Billing

Manage your organization's subscription, update seat counts, view billing information, and configure billing addresses.

Billing tab showing subscription details, seat count, and billing address options

north_east\ \ Learn More\ \ Learn how to manage subscriptions, update seats, and configure billing information.

Models (Organization Management for AI)

The Models section is the organization management area for AI configuration. It appears as a top-level item in the sidebar with two tabs: Models (general settings, allow-lists, processing mode) and API Keys (OpenAI, Anthropic, GCP credentials).

Models section showing general settings and API keys configuration

north_east\ \ Learn More\ \ Configure model allow-lists, processing mode, and API keys for your organization.

Long Term Memory

Configure context capture settings, application sources, denied websites, and default models for memory processing. Long Term Memory is a top-level item in the sidebar.

Long Term Memory section showing Memory Formation toggles and Default Models

north_east\ \ Learn More\ \ Configure context capture, application sources, denied websites, and default models for LTM.

Organization Settings

Configure organization-wide settings that sync to team members' Pieces Desktop and PiecesOS installations. Settings includes General (contact info, address) and Features (External Cloud, Analytics toggles).

Settings page showing tabs for General and Features

north_east\ \ Learn More\ \ Discover how to configure organization settings and control feature toggles.


Next Steps

Now that you understand organization management, learn about Account Settings to manage your personal account, or explore how to create and join organizations.

10

Organization Settings



How to Get to Settings

1

Open the Portal

Go to portal.pieces.app and sign in. Select your organization from the sidebar dropdown if needed.

2

Open Settings

Click Settings in the sidebar navigation.

General Settings

Configure basic organization information, contact details, and address. Update your organization's identity and how Pieces reaches you for billing and support.

General settings tab showing organization name, contact info, and address fields

north_east\ \ Learn More\ \ Learn how to update organization details, contact information, and address.

Features Settings

Toggle organization-wide features that sync to team members' Pieces Desktop and PiecesOS. Control external cloud, analytics, and reporting features.

Features settings tab showing External Cloud and Analytics toggles

north_east\ \ Learn More\ \ Learn how to enable and disable features that sync across your team's installations.

Models and Long Term Memory

Model access, API keys, and Long Term Memory settings are managed from separate sections in the sidebar:

  • Models — Organization management for AI configuration. Click Models in the sidebar to access the Models tab (allow-lists, processing mode) and the API Keys tab (OpenAI, Anthropic, GCP credentials).
  • Long Term Memory — Manage context capture settings, application sources, denied websites, and default models for memory processing. Click Long Term Memory in the sidebar to access.

north_east\ \ Learn More\ \ Configure model access and API keys for your organization.

north_east\ \ Learn More\ \ Configure Long Term Memory settings and context capture.


All organization settings automatically sync to team members' Pieces Desktop and PiecesOS installations, ensuring consistent configuration across your team.

Next Steps

Now that you understand organization settings, learn about Models and API keys to configure AI providers, or explore Long Term Memory to control context capture and default models.

11

Billing & Subscriptions



The Billing page allows you to manage your organization's subscription, view billing details, adjust seat counts, and add billing contact information.

Billing tab showing subscription information, seats, and billing contact

How to Get to Billing

1

Open the Portal

Go to portal.pieces.app and sign in. Select your organization from the sidebar dropdown if needed.

2

Open Billing

Click Billing in the sidebar navigation.

Viewing Subscription Information

1

Open Billing

Go to portal.pieces.app, sign in, and select your organization. Click Billing in the sidebar.

2

View Current Plan

The Subscription Information section displays your current plan (e.g., "Enterprise Seat Yearly") and subscription status shown as an Active or Canceled badge.

3

Review Pricing and Dates

The Billing section shows your pricing breakdown:

  • Price — Cost per seat per billing period (e.g., "$275.99/seat per year")
  • Total — Combined cost for all seats (e.g., "$275.99 per year")
  • Next billing date — When your next payment will be processed
  • Started — Date when your subscription began

Changing Your Plan

Click the Change plan button in the Subscription Information section to view available plans and switch your subscription to a different billing period or tier.

Applying a Discount Code

Apply a discount code to your organization's active subscription. The discount takes effect at your next billing cycle.

1

Click Add Discount

In the Subscription Information section, click the Add discount button.

2

Enter Your Code

In the Add Discount Code modal, type your discount code into the input field.

3

Apply Discount

Click Apply Discount to save. The discount takes effect at your next billing cycle and is reflected on your next invoice.

Changing Seat Count

Update the number of seats in your subscription to accommodate more or fewer team members.

1

Adjust Seat Count

In the Seats section, use the + and - buttons to increase or decrease the number of seats, or type a number directly into the field.

2

Review Minimum Seats

Below the seat count, a message shows how many members you have and the minimum seats required (e.g., "You have 1 member, so you need at least 1 seats"). You cannot set seats below this minimum.

Billing Contact

Add or update billing contact information for invoices and payment correspondence. The Billing Contact section is located below the Subscription Information and Seats sections on the Billing page.

Billing Contact section with fields for name, email, phone, and address

1

Navigate to Billing

From your organization's Home page, click Billing in the sidebar navigation.

2

Locate Billing Contact Section

Scroll down past the Subscription Information and Seats sections. The Billing Contact section appears below, with fields for Name, Email, Phone, Country, Street address, City, State, and ZIP Code.

3

Add or Update Contact Information

If no billing contact is on file, click the Add button to enter your billing contact details. If a contact exists, edit the fields directly. A save reminder appears at the bottom of the page. Click Save to apply.

Understanding Seat Minimums

Your organization must maintain a minimum number of seats based on your active member count.

  • Active Members — Each active member requires one seat
  • Minimum Calculation — Minimum seats equals the number of active members
  • Seat Reduction — You can only reduce seats if you first remove members to free up seats
  • Seat Increase — You can add seats at any time, billed according to your subscription plan

Next Steps

Now that you understand billing, learn about managing members to track seat usage, or explore organization settings to configure team-wide settings.

12

General Settings



The General settings tab allows you to configure basic organization information, contact details, associated domains, SSO integration, and delete your organization. These settings control fundamental aspects of your organization's identity and access.

General settings tab showing organization name, contact info, domains, and danger zone

How to Get to General Settings

1

Open the Portal

Go to portal.pieces.app and sign in. Select your organization from the sidebar dropdown if needed.

2

Open Settings

Click Settings in the sidebar navigation.

3

Select General Tab

Click the General tab at the top. It's the default tab when you open Settings.

Configuring Organization Details

Update basic organization information, domains, and integration settings.

Updating Organization Information

Modify your organization's basic details including name, contact information, and address.

1

Edit Organization Name

In the Organization Name field, update your organization's name as needed.

2

Update Contact Information

Update the following contact fields:

  • Name — Name of the primary contact person
  • Email — Primary email address for the organization
  • Phone — Contact phone number

3

Update Address

Fill in or modify the organization address fields:

  • Country — Select from the dropdown
  • Street address — Enter street address
  • City — Enter city name
  • State — Select state from dropdown
  • ZIP Code — Enter ZIP/postal code

4

Save Changes

A save reminder appears at the bottom of the page. Click Save to apply your changes.

Configuring Associated Domains

Set up domains that are associated with your organization for automatic user assignment.

1

Add Domain

In the Associated Domains section, enter a domain name (e.g., example.com) in the input field.

2

Add Multiple Domains

Click the + button next to the domain field to add additional domains. You can add multiple domains to your organization.

3

Save Domains

A save reminder appears at the bottom of the page. Click Save to save your domain configuration.

Setting Up SSO Integration

Configure SSO (Single Sign-On) integration using a tenant ID for Descope integration.

1

Enter Tenant ID

In the Tenant ID field, enter your Descope tenant ID for SSO integration (e.g., tenant-1234567890).

2

Save Configuration

A save reminder appears at the bottom of the page. Click Save to save your SSO configuration. This is optional and only needed if you're using Descope for SSO integration.

Deleting an Organization

Permanently delete your organization and all associated data. This action cannot be undone.

warning

Deleting an organization is permanent and irreversible. This will permanently delete all organization data, member associations, and billing information. Subscriptions will be cancelled. Make sure you have backups of any important data before proceeding.

1

Navigate to Danger Zone

Scroll down to the bottom of the General settings tab to find the Danger Zone section, which is highlighted in red.

2

Read Warning

Review the warning message that explains what will be deleted:

  • All organization data and settings
  • All member associations
  • All billing and subscription information (subscriptions will be cancelled)

3

Enter Organization Name

Type your organization name exactly as it appears (e.g., "Pieces Test Organization") in the confirmation field to confirm deletion.

4

Delete Organization

Click the Delete Organization button. You'll be asked to confirm this action one more time before the organization is permanently deleted.


Next Steps

Now that you understand general settings, explore other organization settings like Features Settings to configure team-wide features, or check out Models (including the API Keys tab) to configure AI providers and credentials.

13

API Keys



The API Keys tab is one of two tabs within the Models section—the organization management area for AI configuration. From the API Keys tab, you configure credentials for model providers (OpenAI, Anthropic, GCP). These API keys automatically sync to all team members' Pieces Desktop and PiecesOS installations, enabling your team to use these services without individual configuration.

API Keys tab showing OpenAI, Anthropic, and GCP configuration sections

info

All API keys configured here automatically sync to team members' Pieces Desktop and PiecesOS installations, allowing your entire team to use these AI services with organization-managed credentials.

How to Get to the API Keys Tab

1

Open the Portal

Go to portal.pieces.app and sign in. Select your organization from the sidebar dropdown if needed.

2

Open Models

Click Models in the sidebar navigation.

3

Select API Keys Tab

On the Models page, click the API Keys tab at the top.

Configuring API Keys

Set up API credentials for model providers. Each provider has its own configuration section: OpenAI, Anthropic (Claude), and GCP Configuration.

Configuring OpenAI

Set up OpenAI API credentials for your organization.

1

Locate OpenAI Section

Find the OpenAI section with the "API credentials and organization settings."

2

Add API Key

Click the + Add API Key button next to the OpenAI section.

3

Enter Credentials

Fill in the form with:

  • Name (required) — A descriptive name (e.g., "Personal Pro", "Production")
  • API Key (required) — Your OpenAI API key
  • Organization ID (optional) — For OpenAI org-specific usage
  • Project ID (optional) — For project-specific usage
  • Custom API URL (optional) — Defaults to `

4

Save Configuration

A save reminder appears at the bottom of the page. Click Save to save your OpenAI credentials. The credentials will sync to all team members.

Configuring Anthropic (Claude)

Set up Anthropic Claude API credentials for your organization.

1

Locate Anthropic Section

Find the Anthropic (Claude) section with the "API credentials."

2

Add API Key

Click the + Add API Key button next to the Anthropic section.

3

Enter Credentials

Fill in the Anthropic-specific credential form with your API key and any required configuration details.

4

Save Configuration

A save reminder appears at the bottom of the page. Click Save to save your Anthropic credentials.

Configuring GCP

Set up GCP API keys and Vertex AI service accounts for your organization.

1

Locate GCP Section

Find the GCP Configuration section with the "Manage GCP API keys and Vertex AI service accounts."

2

Add API Key

Click the + Add API Key button next to the GCP Configuration section.

3

Enter Credentials

Fill in the GCP-specific credential form with your API key and service account details.

4

Save Configuration

A save reminder appears at the bottom of the page. Click Save to save your GCP credentials.

Managing API Keys

View, edit, and remove existing API key configurations.

Edit API Key form showing name, API key, and optional fields

1

View Configured Keys

Review all configured API keys in their respective sections. Each section shows "No API keys configured" if none are set up.

2

Edit or Remove Keys

Use the edit icon to modify an existing key or the delete icon to remove it. When editing, you can update the name, API key, Organization ID, Project ID, or Custom API URL.

3

Save Changes

A save reminder appears at the bottom of the page. Click Save to apply your changes. A warning appears if you have unsaved changes when navigating away.


Next Steps

Now that you understand API keys settings, explore Models Settings to configure processing mode and model access, or check out Features Settings to configure team-wide feature toggles.

14

Model Settings



The Models section is the organization management area for AI. From here you control which models are available, enable or disable providers (Google, OpenAI, etc.), configure processing mode, and set up API keys. All settings sync to team members' Pieces Desktop and PiecesOS.

Models page showing provider sections (Google, OpenAI) with model lists and toggles

info

All model settings configured here automatically sync to team members' Pieces Desktop and PiecesOS installations.

How to Get to the Models Page

1

Open the Portal

Go to portal.pieces.app and sign in. Or from Pieces Desktop, click your User ProfileSettingsAccount to reach your workspace.

2

Select Your Organization

In the sidebar, click the organization dropdown at the top and select your organization.

3

Open Models

Click Models in the sidebar navigation. The Models page opens with the Models tab selected. Use the API Keys tab to add provider credentials.

Enabling the Customized Model Allow-List

By default, all models from enabled providers are available. To control which providers and models members can use, you must first enable the customized model allow-list. The provider toggles (Google, OpenAI, etc.) are only active when the allow-list is enabled.

1

Enable Customized Model Allow-List

On the Models page, find the Customized Model Allow-List toggle and turn it on.

2

Save

A save reminder appears at the bottom of the page. Click Save to apply. The provider sections below become active so you can enable or disable providers and select specific models.

Enabling or Disabling a Provider (Google, OpenAI, etc.)

info

The customized model allow-list must be enabled for provider toggles to be active. See the section above.

Each provider (Google, OpenAI, Anthropic, etc.) has a toggle at the top of its section. Turn it on to make that provider's models available; turn it off to disable them.

Provider sections with on/off toggles for Google, OpenAI, and other providers

1

Enable Allow-List First

Ensure the Customized Model Allow-List toggle is on near the top of the Models page. Provider toggles are inactive until the allow-list is enabled.

2

Locate the Provider Section

On the Models page, scroll to the provider you want to change (e.g., Google, OpenAI).

3

Toggle the Provider

Use the toggle switch at the top right of the provider section. Turn it on to enable that provider's models for your organization, or off to disable them.

4

Save

A save reminder appears at the bottom of the page. Click Save to apply. Changes sync to all team members.

Selecting Allowed Models

With the allow-list and provider toggles configured, choose which specific models members can use.

1

Scroll to Provider Sections

On the Models page, scroll to each enabled provider (e.g., Google, OpenAI).

2

Select Models

Use the checkboxes or controls next to each model to include or exclude it. Only models you explicitly allow will be available to members.

3

Save

A save reminder appears at the bottom of the page. Click Save to apply.

Setting Organization-Wide Processing Mode

Control whether your organization uses local, cloud, or blended processing for AI features.

1

Enable Organization Managed Processing Mode

On the Models page, find the Organization Managed Processing Mode toggle and turn it on.

2

Choose Processing Mode

Use the Organization-Wide Processing Mode dropdown to select:

  • BLENDED — Mix of local and cloud (recommended)
  • Local — Process locally only (limits features)

3

Save

A save reminder appears at the bottom of the page. Click Save to apply. The chosen mode applies to all organization members.

lightbulb

Blended mode is recommended. Local-only mode severely limits AI features.

Adding API Keys for Providers

To use models from OpenAI, Anthropic, or GCP, you need to add API keys. Switch to the API Keys tab within Models.

1

Open API Keys Tab

On the Models page, click the API Keys tab at the top.

2

Add a Key

Find the provider section (OpenAI, Anthropic, GCP) and click + Add API Key. Enter your credentials and click Save.

3

Return to Models

Switch back to the Models tab to enable that provider and choose which models to use.

For full API key instructions, see API Keys Settings.


Next Steps

Add credentials in API Keys, or configure Long Term Memory for context capture and default models.

15

Feature Toggles



The Features settings tab allows you to control organization-wide feature toggles that automatically sync to all team members' Pieces Desktop and PiecesOS installations. These settings ensure consistent feature availability across your team.

Features settings tab showing various feature toggles and processing options

info

All feature settings configured here automatically sync to team members' Pieces Desktop and PiecesOS installations, ensuring everyone has the same feature availability.

How to Get to Features Settings

1

Open the Portal

Go to portal.pieces.app and sign in. Select your organization from the sidebar dropdown if needed.

2

Open Settings

Click Settings in the sidebar navigation.

3

Select Features Tab

Click the Features tab at the top of the Settings page.

Feature Categories

Configure organization-wide features organized by category. All feature settings automatically sync to team members' Pieces Desktop and PiecesOS installations. Model access, processing mode, and API keys are configured in the Models section (organization management for AI).

External Cloud

Control cloud-related operations and features for your organization.

1

Locate External Cloud Section

Find the External Cloud section in the Features tab.

2

Toggle External Cloud

Use the toggle switch next to External Cloud to enable or disable cloud connectivity, backup management (create, list, restore, delete), snippet sharing, and cloud allocation updates.

3

Save Changes

A save reminder appears at the bottom of the page. Click Save to apply. The setting will sync to all team members.

Analytics

Configure analytics and reporting features for your organization.

1

Locate Analytics Section

Find the Analytics section in the Features tab.

2

Toggle Telemetry

Use the toggle switch next to Telemetry to enable or disable BigQuery and Segment analytics integrations.

3

Toggle Send Internal Summary Reports

Use the toggle switch next to Send Internal Summary Reports to enable or disable sending internal summary reports to user team service.

4

Save Changes

A save reminder appears at the bottom of the page. Click Save to apply your analytics settings.


Next Steps

Now that you understand features settings, explore Models and API Keys to configure AI providers and processing mode, or check out Long Term Memory to configure context capture and default models.

16

Long Term Memory (LTM)



The Long Term Memory section allows you to configure context capture settings, manage which applications and websites Pieces can access, and set default models for memory processing. These settings automatically sync to all team members' Pieces Desktop and PiecesOS installations. Long Term Memory is a top-level section in the organization sidebar.

Long Term Memory section showing Memory Formation toggles and Default Models

info

All Long Term Memory settings configured here automatically sync to team members' Pieces Desktop and PiecesOS installations, ensuring consistent context capture and model configuration across your team.

lightbulb

To enable LTM websites or applications: turn on the corresponding toggle in the General tab, then use the Applications or Websites tab to manage what's blocked. To fully turn off: turn the toggle off in the General tab.

How to Get to Long Term Memory

1

Open the Portal

Go to portal.pieces.app and sign in. Select your organization from the sidebar dropdown if needed.

2

Open Long Term Memory

Click Long Term Memory in the sidebar navigation.

3

Choose a Tab

The General tab shows Memory Formation toggles and Default Models. Use Applications and Websites tabs to manage blocked apps and sites after enabling their toggles.

Enabling Memory Formation Toggles

The General tab has three toggles that control how Pieces captures context. Turn them on or off as needed.

1

Enable Audio Context Capture

In the General tab, find Audio Context Capture and turn the toggle on to let Pieces process audio (meetings, conversations) for memory. Turn off to disable.

2

Enable Organization Managed Application Sources

Turn the Organization managed application sources toggle on to control which applications Pieces can access. When on, click Manage applications or open the Applications tab to allow or block apps. Turn off to disable organization-managed app control.

3

Enable Organization Managed Denied Websites

Turn the Organization managed denied websites toggle on to block specific websites from Long Term Memory. When on, click Manage websites or open the Websites tab to add blocked sites. Turn off to disable organization-managed website blocking.

4

Save

A save reminder appears at the bottom of the page. Click Save to apply. Settings sync to all team members.

Configuring Default Models

Default models are used for memory event processing, auto-generated summaries, and audio transcription. Configure them after setting up API keys in Models.

Default Models section on the LTM General tab showing model assignment options

1

Click Manage Models

In the General tab, find the Default Models section and click the Manage models button.

2

Assign Models

For each feature (Memory event processing, Auto-generated summaries, Audio transcription), choose a primary model and optional fallback. Models come from your enabled providers and API keys.

3

Save

A save reminder appears at the bottom of the page. Click Save to apply. Default models sync to all team members.

Managing Application Access

When Organization managed application sources is enabled in the General tab, click the Manage applications button or select the Applications tab to manage which applications Pieces can access for context capture.

Available applications list showing application names, bundle IDs, and toggle switches

Viewing Applications

The Applications tab shows two sections: Blocked Applications (apps blocked from context capture) and Available Applications (apps that can be allowed or blocked). Each application has a toggle to enable or disable it for context capture.

1

Select Applications Tab

Click the Applications tab at the top of the Long Term Memory page.

2

Review Application List

The Available Applications section displays applications Pieces can access. Each application shows:

  • Application name
  • Global tag (if applicable)
  • Related bundle IDs and identifiers

3

Search Applications

Use the search bar at the top with the placeholder "Search applications by name..." to quickly find specific applications.

4

View Application Status

Each application has a toggle switch. Turn it on to allow context capture from that application, or off to block it.

Adding New Applications

Add custom applications to control access for specific tools your team uses.

1

Click Add Application

Click the + Add Application button at the top of the Applications tab.

2

Enter Application Name

In the Add New Application modal, enter the application name in the Application Name field (e.g., "Chrome", "Safari", "Firefox").

3

Add Bundle IDs

In the Bundle IDs field, enter bundle identifiers to help identify specific applications (e.g., com.example.app). Click the + icon to add multiple bundle IDs.

4

Create Application

Click the Create button to add the application to your list. The application will appear in the Available Applications section.

Enabling or Disabling Applications

Toggle access on or off for specific applications. Enable an application to allow context capture from it; disable it to block it from Long Term Memory.

1

Locate Application

Find the application in the Blocked Applications or Available Applications list.

2

Toggle Access

Use the toggle switch next to the application name. Turn on to allow context capture, or off to block it.

3

Save Changes

A save reminder appears at the bottom of the page. Click Save to apply. The settings will sync to all team members.

Understanding Global vs Organization Settings

Some applications may have a Global tag, indicating they are system-wide applications. Organization-specific settings allow you to override or supplement global settings for your team.

  • Global Applications - System-wide applications that affect all users
  • Organization Settings - Your organization's specific access controls that sync to team members

Next Steps

Now that you understand LTM sources settings, explore LTM Websites Settings to configure which websites Pieces is denied from accessing, or check out Features Settings to configure team-wide features.

17

LTM Websites & Blocked Sites



The LTM Websites settings allow you to configure which websites are blocked from Long Term Memory. You must enable Organization managed denied websites in the General tab first; then use the Websites tab to add blocked sites. Disable the toggle to fully turn off organization-managed website blocking. These settings automatically sync to all team members' Pieces Desktop and PiecesOS installations.

Blocked websites list with add input and CSV upload

info

All LTM website settings configured here automatically sync to team members' Pieces Desktop and PiecesOS installations, ensuring consistent blocked website lists across your team.

Accessing LTM Websites Settings

Enable the toggle in the General tab, then use the Websites tab to manage blocked sites.

Enabling Organization managed denied websites in the General tab

1

Open Long Term Memory

From your organization's Home page, click Long Term Memory in the sidebar navigation.

2

Enable Organization Managed Denied Websites

In the General tab, turn on the Organization managed denied websites toggle in the Memory Formation section. You can also click the Manage websites button to jump to the Websites tab.

3

Open Websites Tab

Click the Websites tab at the top of the Long Term Memory page to add or manage blocked websites.

Managing Blocked Websites

The Blocked websites section lists sites that will not be tracked or used for Long Term Memory. Add websites individually or upload multiple sites via CSV.

Adding Blocked Websites Manually

Add individual websites to the blocked list.

1

Enter Website URL

In the input field (placeholder: "example.com or ), enter the URL or domain you want to block (e.g., example.com or `).

2

Add Website

Click the + Add button to add the website to your blocked list.

3

Save Changes

A save reminder appears at the bottom of the page. Click Save to apply. Your blocked websites list will sync to all team members.

Bulk Uploading Blocked Websites

Upload multiple websites at once using a CSV file. Format: one website per line.

1

Prepare CSV File

Create a CSV file with one website URL or domain per line. For example:


another-site.com
third-site.com

content_copy

2

Upload CSV

Click the Upload CSV button or drag and drop your CSV file into the upload area.

3

Review and Save

Review the imported websites. A save reminder appears at the bottom of the page. Click Save to add them to your blocked list.

Removing Blocked Websites

To allow a website for Long Term Memory again, remove it from the blocked list.

1

Locate Website

Find the website in the Blocked websites list.

2

Remove Website

Click the trash icon next to the website to remove it from the blocked list.

3

Save Changes

A save reminder appears at the bottom of the page. Click Save to apply your changes.

Understanding Blocked Websites

When a website is added to the Blocked websites list, it will not be tracked or used for Long Term Memory. This helps you control what information Pieces can collect and use.

  • Privacy Control — Prevent Pieces from accessing sensitive or private websites
  • Team Consistency — All team members share the same blocked website list
  • Fully Disable — Turn off the Organization managed denied websites toggle in the General tab to disable organization-managed website blocking entirely

Next Steps

Now that you understand LTM websites settings, explore LTM Applications to control which applications are blocked or allowed for context capture, or check out Features Settings to configure team-wide features.

18

What's Included in Enterprise



Pieces Enterprise includes features designed for teams and organizations at scale. Admin controls, security, and compliance options help you deploy Pieces across your engineering organization.

Organization Home page showing admin dashboard, management tools, and resource links

Enterprise Features

  • Organizations & Teams — Create organizations and invite members
  • Centralized Settings — Manage models, API keys, and configuration at the org level
  • Shared Context — Organization members can share materials, snippets, and workflow context
  • Admin Dashboard — Overview of members, usage, and organization health

Security & Compliance

  • Role-based Access — Owners, admins, and members with appropriate permissions
  • Audit Logs — Track changes and access for compliance
  • Data Residency — Options for data location and retention
  • SSO — Single Sign-On for enterprise authentication

info

For specific security and compliance requirements, contact your Pieces account team or enterprise@pieces.app.

Admin Controls

Organization owners and admins can:

  • Invite and remove members
  • Manage member roles and access
  • Configure billing and subscription
  • Manage API keys and model settings
  • Control feature access per member

See Organization Settings for feature toggles, API keys, models, and LTM sources. For onboarding, see Onboarding Users. For organization structure, see Organizations.

19

Troubleshooting



If you encounter issues when creating, accessing, or managing organizations, use this guide to resolve common problems.

Troubleshooting guide showing common issues and solutions

"Loading your workspace..." Stuck Issue

If you get stuck on a "Loading your workspace..." screen when trying to access your organization, you can resolve this by forcing a logout and re-authenticating.

1

Navigate to Logout Page

In your browser, navigate directly to portal.pieces.app/auth/logout. This will forcefully sign you out of your current session.

2

Wait for Logout

Wait for the logout process to complete. You should be redirected to a sign-in page or see a confirmation that you've been logged out.

3

Sign Back In

Navigate to portal.pieces.app/auth/login and sign back in with your account credentials.

4

Access Your Workspace

After signing back in, you should be able to access your Personal Workspace and organizations without the loading issue.

Cannot Access Organization After Creation

If you've created an organization but cannot access it:

1

Check Email Confirmation

Verify that you received a success email confirming your organization creation. Check your spam folder if you don't see it.

2

Verify Authentication

Ensure you're signed in to the correct account that was used to create the organization.

3

Try Logout and Login

Use the logout/login process described above to refresh your session.

4

Check Organization Dropdown

In your Personal Workspace, check the organization dropdown in the sidebar to see if your organization appears in the list.

Cannot Accept Organization Invitation

If you're having trouble accepting an organization invitation:

1

Check Email Link

Make sure you're clicking the invitation link from the email sent by the organization owner or admin.

2

Verify Account

Ensure you're signed in to the account that matches the email address the invitation was sent to.

3

Try Direct Login

If the invitation link doesn't work, try logging in directly at portal.pieces.app/auth/login, then check your Personal Workspace for the organization.

4

Contact Organization Admin

If you still cannot accept the invitation, contact the organization owner or admin to verify the invitation status and resend if needed.

Cannot Use Pieces After Joining Organization

If you've joined a new organization but cannot use Pieces until you configure models:

1

Open Settings

In Pieces Desktop, navigate to Settings by clicking your profile picture in the top left and selecting Settings, or use the keyboard shortcut ⌘+, (macOS) or ctrl+, (Windows/Linux).

2

Navigate to Models Tab

In the Settings sidebar, click on the Models tab or category.

3

Configure Models

Toggle all models on, or select the specific models you want to use from the available options.

4

Save Changes

A save reminder appears at the bottom of the page. Click Save to apply your model selections. After saving, you should be able to use Pieces with your organization.

Organization Not Appearing in Dropdown

If your organization doesn't appear in the organization dropdown:

1

Refresh Page

Try refreshing your browser page to reload the organization list.

2

Check Multiple Organizations

If you belong to multiple organizations, scroll through the dropdown list to find the one you're looking for.

3

Verify Membership

Confirm that you're still a member of the organization. Contact the organization owner or admin if you believe you should have access.

4

Try Logout and Login

Use the logout/login process to refresh your session and organization list.

Settings Not Syncing to Desktop

If organization settings aren't appearing in your Pieces Desktop installation:

1

Verify Organization Membership

Confirm that you're a member of the organization and that settings have been configured by an Owner or Admin.

2

Check Desktop Connection

Ensure your Pieces Desktop is connected to your account and signed in.

3

Restart Desktop Application

Try restarting your Pieces Desktop application to allow settings to sync.

4

Check Settings Tab

In Pieces Desktop, check if there's an organization settings section that shows synced settings.

5

Contact Support

If settings still don't sync, contact support for assistance with organization settings synchronization.

Getting Additional Help

If you continue to experience issues after trying the solutions above, here are additional resources:

  • Account Settings Documentation - Check the Account Settings documentation for account-related issues
  • Setup Guide - Review the Creating and Joining Organizations guide for setup issues
  • Support Team - Set up a call with our support team to get personalized assistance
  • Organization Admin - Reach out to your organization Owner or Admin for organization-specific issues

Next Steps

If you've resolved your issue, learn about managing organizations to explore admin features, or check out creating and joining organizations if you're setting up a new organization.

For the full Organizations & Teams documentation, see Organizations & Teams.

Unofficial community-compiled SOP documentation for Pieces for Developers.