Projects
Projects provide data isolation and access control to collections of resources within an organization. Every device, event, recording, session, episode, and dataset belongs to one Project.
What can you do with Projects?
Projects enable you to organize data and control access within your organization.
- Separate production and development workflows
- Organize data by team or customer
- Share subsets of data with specific members
- Restrict third parties or external contractors to specific data within your Foxglove organization
Creating a Project
Every organization starts with a single shared Project that all members can access. Admins can create additional Projects from the Projects page. Pro and Academic plans allow up to 3 Projects, and Enterprise plans allow unlimited Projects.
Before creating a second Project, ensure all programmatic uploads specify a Project or existing device. See below.
Access control
A Project can either be invite-only or shared. Invite-only Projects require explicit assignments for non-admin members, while shared Projects are available to all members of the organization. Admins can assign members to Projects via the Members page and change the invite-only status of a Project via the Projects page.
- Members with the user role can only see and access shared Projects and Projects they are assigned to.
- Members with the admin role can access all Projects.
- Organization API keys can access all Projects unless they are limited to some of them.
- Personal access tokens can access the Projects their owner can, unless they are limited to some of them.
Projects are isolated. Data in one Project cannot be accessed from or moved to another Project.
Pending imports not yet associated with a Project are only visible to admins via the Pending Imports page. This can happen when uploads don't specify a device or Project ID — for example, at self-hosted sites where metadata isn't included during the upload. To ensure non-admin members can track their imports, always include a device or Project ID.
Associating data
We recommend always providing a Project ID when interacting with Foxglove programmatically. For organizations with multiple Projects, a Project ID is required when creating devices or uploading recordings without an existing device.
Project IDs can be found on the Projects page.
API requests
Endpoints that create or list Project scoped resources accept a projectId field to specify the Project. See API docs for more information.
Self-hosted Primary Sites
Providing a foxglove_project_id record in object metadata or a projectId in MCAP metadata associates the upload with a Project. See Site docs for more information.
Self-hosted Primary Sites support Projects as of version 0.0.69.
Web and desktop apps
Uploading files and creating devices from the Foxglove dashboard automatically associates them with the current Project.
Project vs Organization scoped resources
Every device, event, recording, session, episode, and dataset belongs to a single Project. Data in one Project cannot be accessed from another Project.
Resources at the organization level work across all Projects.
| Resource | Project | Organization |
|---|---|---|
| Automations | ✓ | |
| Datasets | ✓ | |
| Devices | ✓ | |
| Episodes | ✓ | |
| Events | ✓ | |
| Recordings | ✓ | |
| Saved searches | ✓ | |
| Sessions | ✓ | |
| API keys and personal access tokens | ✓ | |
| Custom properties | ✓ | |
| Event types | ✓ | |
| Extensions | ✓ | |
| Layouts | ✓ | |
| Sites | ✓ | |
| Webhooks | ✓ |
Limit API keys and personal access tokens
Limit an organization API key or a personal access token to specific Projects when it only needs some of your data. For example, give a script that processes one team's recordings a key that can only reach that team's Project.
Choose Projects in the Projects field when you create or edit the key. The field appears when your plan supports Projects. Leave it empty to allow every Project, including Projects added later. To keep a key away from Projects added later, choose its Projects, even if there's only one.
The rules below apply to both API keys and personal access tokens. They differ in who can limit them and which Projects they can reach. See Differences between API keys and tokens.
What a limited key can do
A limited key can:
- Read and change data in its Projects, within its capabilities
- Read organization-wide resources: layouts, extensions, event types, custom properties, and sites
A limited key can't:
- Read or change data in other Projects
- Create, change, or delete organization-wide resources, because a change affects every Project
- Read or change site ingest path policies or backfill jobs
- Manage site tokens or site inbox notification tokens
- List organization members
When you choose a Project, the dialog disables the capabilities a limited key can't use. To do any of these things, use a key that isn't limited to Projects.
Call the API with a limited key
If a key can reach only one Project, requests use that Project automatically. If it can reach more than one, include a projectId in requests to most endpoints that accept one. A few endpoints, such as creating an event or listing datasets, use all of the key's Projects when you leave it out. See the API reference for each endpoint's parameters.
A limited key can get these errors:
| Status | Message or code | Cause |
|---|---|---|
| 400 | projectId is required | The key can reach more than one Project, and the request didn't include a projectId. |
| 404 | Project not found | The projectId isn't one of the key's Projects. |
| 403 | ProjectLimitedCredentialDenied | A limited key can't make this request, for example changing a layout. |
| 403 | NoAccessibleProjects | None of the key's Projects remain. Edit the key to choose other Projects, or replace it. |
Change a key's Projects
Edit the key to add or remove Projects. Its Projects stay the same unless you change them. Saving removes any selected capabilities that a limited key can't use.
Projects the key can no longer reach are shown as Unknown project. Remove them before you change the key's Projects, or saving fails. If you remove every Project, the limit is removed and the key can reach every Project.
Differences between API keys and tokens
| Organization API key | Personal access token | |
|---|---|---|
| Who can limit it | Admins | The token's owner |
| Projects you can choose | Every Project in the organization | The Projects you can access |
| An empty Projects field allows | Every Project, including ones created later | Every Project you can access, including ones you get access to later |
| The key can no longer reach a Project | When the Project is deleted | When the Project is deleted, or when you lose access to it |
A personal access token can't manage site tokens or site inbox notification tokens, even without a limit.