Skip to main content

Personal access tokens

Use a personal access token to call the Foxglove API from your own scripts. Each token is tied to your membership in the organization where you create it. Its access is limited by both the capabilities you select and your current role, seat, and Project access. It stops working if you leave the organization.

Open Settings → Personal access tokens.

Personal access tokens settings page listing two tokens

Create and use a token​

  1. Click Create personal access token.
  2. Enter a Label that identifies the script or workflow that will use it.
  3. Choose an Expiration. The default is 90 days. Choose Never for no expiration date.
  4. Optionally, choose the Projects the token can reach. Leave it empty to allow every Project you can access. See Limit a token to Projects.
  5. Select the Capabilities the script needs. Capabilities that your plan, role, or seat doesn't allow show why you can't select them. Personal access tokens can't manage credentials, including creating other tokens, so the list doesn't show those capabilities.
  6. Click Create and copy the secret. It appears only once, so store it securely.

Create personal access token dialog with a label, the default expiration, and selected capabilities

Send the secret in the Authorization: Bearer <token> header when calling the API. Keep it out of source control and logs. Requests use your organization's API rate limit, with an additional limit shared by all your personal access tokens.

Actions made with a personal access token are attributed to you. Supported audit events also identify which token performed the action.

Limit a token to Projects​

If you can access more than one Project, you can limit a token to some of them. A limited token can't read or change data in other Projects, even if you're an admin. If you lose access to one of its Projects, the token loses access too.

Organization-wide resources, such as layouts, custom properties, event types, and extensions, aren't limited by Project. A token limited to Projects can still list, create, and edit custom properties, but can't delete one, because deleting a custom property removes its values from devices and sessions in every Project. A token limited to Projects can list and create sites, but can't rename a site, change its retention or URL, or delete it. It also can't read or change site ingest path policies or backfill jobs, or create, list, or delete site tokens or site inbox notification tokens, because those reach every Project.

When a token is limited to more than one Project, most endpoints that accept a projectId parameter require it. They return a 400 error with the message projectId is required when it's omitted. Other endpoints that return Project data return data from all of the token's Projects.

Edit, replace, or delete a token​

Click Edit beside an unexpired token to change its capabilities or Projects, then click Save. The secret stays the same. Saving removes any selected capabilities that your current plan, role, or seat no longer permits. The token's Projects stay the same unless you change them. Projects that no longer exist or that you can no longer access are shown as Unknown project. Remove them before you change the token's Projects.

To change a token's label or expiration, or replace an expired token, create a replacement. Replace it before it expires to avoid interrupting your scripts:

  1. Create a token with the required capabilities.
  2. Update your scripts to use the replacement and confirm they work.
  3. Wait until the existing token's Last seen date stops changing, then click Delete and confirm. Last seen shows only the date, so a token used earlier today still shows today's date.

Deleting a token permanently revokes its access. Cached authentication can take about 10 seconds to expire, and download URLs already issued keep their own expiration times. You can manage tokens only from your signed-in session. A personal access token or API key can't create, edit, or delete personal access tokens.

You can have up to 50 personal access tokens per organization. Expired tokens count toward this limit until you delete them.

Plan changes​

Personal access tokens are available on Pro, Enterprise, and Academic plans. On other plans, the Personal access tokens page shows an upgrade prompt instead of Create personal access token. Admins can follow it to billing settings, and other members are asked to contact an admin.

If your organization moves to a plan without personal access tokens, existing tokens stop working on the next request. Requests made with them fail with a 403 error and the code PersonalApiKeysPlanRequired. You can still see and delete them, but not edit them. Tokens you don't delete work again after the organization upgrades.