diff --git a/fern/products/platform/pages/getting-started.mdx b/fern/products/platform/pages/getting-started.mdx
index adf97ea380..6ae9079746 100644
--- a/fern/products/platform/pages/getting-started.mdx
+++ b/fern/products/platform/pages/getting-started.mdx
@@ -272,6 +272,20 @@ const client = RestClient(PROJECT_ID, API_TOKEN, {
## Core concepts
+### Projects and Subprojects
+
+A **Project** groups everything you build: phone numbers, Resources, and API credentials.
+Every Space starts with one, and you can add more at any time.
+
+Beneath a Project you can nest **Subprojects**, one level deep.
+A Subproject is a full Project with its own Project ID, API tokens, and Resources, which makes it a
+clean way to isolate a customer, a tenant, or a staging environment.
+Unlike root Projects, Subprojects can be created and deleted through the API.
+
+
+ What a Project scopes, and how Subprojects nest beneath one
+
+
### Communication channels
SignalWire supports the following communication channels:
@@ -329,21 +343,21 @@ We also offer the option of purchasing phone numbers programmatically via our [P
In SignalWire, a **Resource** is anything that can handle communications - an AI agent, a script, a SIP connection, or your own application.
When a call or message comes in, you tell SignalWire which Resource should handle it.
-Common resource types include:
+Common Resource types include:
- **SWML Scripts** - Simple JSON/YAML instructions hosted in your Dashboard
- **AI Agents** - Conversational AI that handles calls autonomously
- **Call Flows** - Visual drag-and-drop call routing
- **Relay Applications** - Your own server applications connected via WebSocket
- Understanding the different resource types
+ Understanding the different Resource types
### Addresses
Every Resource has an **Address**.
This is a unique identifier that lets you target and interact with it.
-Think of addresses as the **phone number** for any resource, but broader in scope.
+Think of addresses as the **phone number** for any Resource, but broader in scope.
Addresses can be:
- **Phone numbers** - Traditional numbers like `+14155551234` for PSTN calls
diff --git a/fern/products/platform/pages/platform/core/projects.mdx b/fern/products/platform/pages/platform/core/projects.mdx
new file mode 100644
index 0000000000..994468dc5b
--- /dev/null
+++ b/fern/products/platform/pages/platform/core/projects.mdx
@@ -0,0 +1,126 @@
+---
+title: Projects
+description: Projects group the phone numbers, Resources, and credentials in your Space, and Subprojects nest one level beneath a root Project with their own Project ID and Resources.
+slug: /projects
+max-toc-depth: 3
+---
+
+A Project is the container for what you build in a SignalWire Space.
+Phone numbers, [Resources](/docs/platform/resources), and
+[API credentials](/docs/platform/your-signalwire-api-space) all belong to exactly one Project,
+which is how you group work by customer, by environment, or by any other classification you like.
+
+Your Space starts with one Project, created alongside the Space itself, and you can add more
+at any time.
+
+## What a Project scopes
+
+Each Project carries its own Project ID and its own API tokens, and every request you make is
+authenticated as one Project and acts on that Project alone.
+
+Security settings belong to the Project too.
+Each Project has its own [media URL protection](/docs/platform/media-protection) settings for
+recordings, message media, and fax media, and its own choice of whether webhooks and callbacks
+must use HTTPS.
+
+Not everything divides along Project lines.
+Voice and messaging [rate limits](/docs/platform/rate-limits) are account-level, counted across
+every Project in your Space.
+
+## Work with Projects in the Dashboard
+
+The Project name at the top of the Dashboard opens the Project menu, where every Project-level
+action starts:
+
+- **Project Configuration** opens the active Project's settings, including its
+ [media URL protection](/docs/platform/media-protection) toggles.
+- **Switch Project** changes which Project the Dashboard shows.
+- **Create New Project** adds a Project to your Space.
+
+
+
+
+ 
+
+
+
+
+A Project's Project ID, Space URL, API tokens, and signing key are on its
+[API Credentials](/docs/platform/your-signalwire-api-space) page, which always shows the active
+Project — switch Projects to reach another one's credentials.
+
+## Subprojects
+
+A Subproject is a Project nested one level beneath a root Project.
+It is a full Project with its own Project ID and Resources, but a Subproject cannot contain other
+Subprojects.
+
+Unlike root Projects, Subprojects can be created and deleted through the API, so an application can
+open and retire a Project per customer, per tenant, or per environment on its own.
+Root Projects are created in the Dashboard and can't be deleted through the API.
+
+### Create a Subproject
+
+Authenticate as the root Project and send the Subproject's name, along with any security settings
+you want it to start with.
+A Subproject cannot create another Subproject, so a request authenticated as a Subproject fails
+with `422 nested_subprojects_not_allowed`.
+
+
+
+SignalWire signs every request it makes to your webhooks with the Project's `signing_key`, so your
+server can [verify that a request really came from SignalWire](/docs/swml/guides/webhook-security).
+The create response is the only place the API returns that key, so capture it here.
+Afterward you can read it from the new Project's **API Credentials** page in the Dashboard, or
+replace it with
+[Rotate a project's signing key](/docs/apis/rest/projects/rotate-signing-key).
+
+
+
+To get credentials for the new Subproject, call
+[Create API token](/docs/apis/rest/project-tokens/create-token) from the root Project with the
+Subproject's ID in `subproject_id`.
+
+### Delete a Subproject
+
+Only Subprojects can be deleted through the API; targeting the root Project returns
+`422 only_subprojects_can_be_deleted`.
+
+
+
+A Project must have no phone numbers before it can be deleted, or the request returns
+`422 phone_numbers_must_be_removed`.
+Deleting a Subproject also migrates its registry brands and campaigns up to the parent Project.
+
+
+
+
+
+## Manage Projects through the API
+
+Every Projects API request reaches only the authenticated Project and the Subprojects beneath it.
+[List projects](/docs/apis/rest/projects/list-projects) returns the authenticated Project
+alongside its Subprojects, and each entry reports whether it is a Subproject and which Project it
+belongs to.
+A Project ID outside that tree returns `404 Not Found`.
+
+[Update a project](/docs/apis/rest/projects/update-project) changes the name and security settings
+of any Project in that tree, root Project included.
+[Rotate a project's signing key](/docs/apis/rest/projects/rotate-signing-key) issues a new
+webhook-signing key for one; the old key keeps working for a minute or two.
+
+Integrations built around Compatibility API Account SIDs see the same tree as Accounts:
+[Create Subprojects](/docs/compatibility-api/rest/accounts/create-subprojects) and
+[List accounts](/docs/compatibility-api/rest/accounts/list-accounts) cover the same ground with
+form-encoded requests.
+
+## Next steps
+
+
+
+ Every operation for listing, creating, updating, and deleting Projects.
+
+
+ Find a Project's Project ID and Space URL, and issue API tokens.
+
+
diff --git a/fern/products/platform/pages/platform/setup/api-credentials.mdx b/fern/products/platform/pages/platform/setup/api-credentials.mdx
index 820232bd13..669cd48c44 100644
--- a/fern/products/platform/pages/platform/setup/api-credentials.mdx
+++ b/fern/products/platform/pages/platform/setup/api-credentials.mdx
@@ -17,7 +17,7 @@ The API credentials found on this page are your key to accessing SignalWire's AP
-Open **API Credentials** in the Dashboard to find the current project's **Project ID** and **Space URL**. Reveal and copy an existing API token or select **+ New** to create one.
+Open **API Credentials** in the Dashboard to find the current Project's **Project ID** and **Space URL**. Reveal and copy an existing API token or select **+ New** to create one.
@@ -25,14 +25,17 @@ Most SignalWire API endpoints require authentication using
[HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication).
HTTP Basic Authentication requires you to send an Authorization header with your Project ID and API Token.
-Each project has its own Project ID and API Authentication Tokens you will need to use when making a request to the API.
+Each Project has its own Project ID and API Authentication Tokens you will need to use when making a request to the API.
Some methods will also require you to pass your Space URL.
+[Subprojects](/docs/platform/projects#subprojects) work the same way: each one has its own Project ID and tokens,
+and a root Project can issue a token for one of its Subprojects with
+[Create API token](/docs/apis/rest/project-tokens/create-token).
- **Project ID:** Use this UUID to specify your Project to the API.
- **Space URL:** Use this URL to access SignalWire APIs.
For example: `https://{Your_Space_Name}.signalwire.com/api/calling/calls`
- **API Tokens:** Authentication tokens to access the API.
-You can have multiple tokens for each project.
+You can have multiple tokens for each Project.
@@ -92,7 +95,7 @@ This example uses curl with the `-u` flag to make a request with Basic Auth.
```shell
curl https://.signalwire.com/api/video/rooms \
- -u ':'
+ -u ':'
```
@@ -109,7 +112,7 @@ import axios from "axios";
await axios
.get("https://.signalwire.com/api/video/rooms", {
- auth: { username: "", password: "" },
+ auth: { username: "", password: "" },
})
.then((response) => {
console.log(JSON.stringify(response.data));
@@ -129,7 +132,7 @@ Or with the **Realtime SDK**, you may use these credentials to create a Video Cl
import { Video } from "@signalwire/realtime-api";
const video = new Video.Client({
- project: "",
+ project: "",
token: "",
});
```
diff --git a/fern/products/platform/pages/platform/setup/create-an-account.mdx b/fern/products/platform/pages/platform/setup/create-an-account.mdx
index b2320e01b7..8b653ea665 100644
--- a/fern/products/platform/pages/platform/setup/create-an-account.mdx
+++ b/fern/products/platform/pages/platform/setup/create-an-account.mdx
@@ -49,18 +49,29 @@ Keep the following in mind:
Once set, your Space domain cannot be changed except by a Support request.
You can create multiple Spaces associated with your SignalWire account.
- Each Space can contain multiple Projects.
+ Each Space can contain multiple Projects, and each Project can contain Subprojects.
-### Create a project
+### Create a Project
-Projects are used to group resources according to your preference, such as by customer account, by geographical region, or any other classification.
-Name your project something that will help to distinguish it from the other projects you will make in the future, and you're ready to go.
+Projects are used to group Resources according to your preference, such as by customer account, by geographical region, or any other classification.
+Name your Project something that will help to distinguish it from the other Projects you will make in the future, and you're ready to go.
-Now you have a SignalWire Space and your first project. Congratulations!
+Now you have a SignalWire Space and your first Project. Congratulations!
+## Group work with Projects and Subprojects
+
+You can add more [Projects](/docs/platform/projects) to your Space at any time from the Project
+menu in the Dashboard.
+A Project can also hold [Subprojects](/docs/platform/projects#subprojects): Projects nested one
+level beneath it, each with its own Project ID, API tokens, phone numbers, and Resources.
+Use a Subproject to give a customer, an environment, or a region an isolated Project.
+Unlike root Projects, an application can create and delete Subprojects through the REST API, with
+[Create a subproject](/docs/apis/rest/projects/create-subproject) and
+[Delete a subproject](/docs/apis/rest/projects/delete-subproject).
+
---
## Next steps