Skip to main content

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.

warning

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.

note

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.

ResourceProjectOrganization
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:

StatusMessage or codeCause
400projectId is requiredThe key can reach more than one Project, and the request didn't include a projectId.
404Project not foundThe projectId isn't one of the key's Projects.
403ProjectLimitedCredentialDeniedA limited key can't make this request, for example changing a layout.
403NoAccessibleProjectsNone 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 keyPersonal access token
Who can limit itAdminsThe token's owner
Projects you can chooseEvery Project in the organizationThe Projects you can access
An empty Projects field allowsEvery Project, including ones created laterEvery Project you can access, including ones you get access to later
The key can no longer reach a ProjectWhen the Project is deletedWhen 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.