Skip to main content

Generating API Tokens

info

We talk about the Polar Signals Agent here which for now is the same code as the Parca Agent.

Generating API Tokens to set up continuous profile collection (Polar Signals Agent)​

An agent is set up through the use of the Polar Signals Agent which can be configured to continuously send profiles to the Polar Signals Cloud. In order to set up the Polar Signals Agent on a Kubernetes cluster, you must first create a service account and generate an API token in the Polar Signals Cloud UI.

Understanding Service Accounts and Tokens​

Polar Signals Cloud uses a role-based access control (RBAC) system for API authentication. Instead of project-specific JWT tokens, the system now uses service account tokens:

  • Service Accounts: Named identities that can be granted specific permissions through role bindings
  • Service Account Tokens: API tokens associated with a service account (format: psc_v1_<64-hex-characters>)
  • Role Bindings: Assignments that grant a service account specific roles and permissions

This approach provides more granular control over what each token can access and do. The project to which data is sent is specified separately via the projectID gRPC metadata header.

Creating a Service Account and Token​

Step 1: Navigate to IAM Settings​

  1. Go to your organization settings
  2. Navigate to the IAM tab
  3. Select the Service Accounts section

IAM Service Accounts page

Step 2: Create a Service Account​

  1. Click Create Service Account
  2. Enter a descriptive name (e.g., "kubernetes-production-agent")
  3. Click Create

Create Service Account modal

Step 3: Assign Roles to the Service Account​

After creating the service account, you need to grant it appropriate permissions:

  1. Go to the Role Bindings section in the IAM tab
  2. Click Create Role Binding
  3. Select your service account as the subject
  4. Assign appropriate roles (e.g., writer or profile-writer for agents that need to send profiling data)
  5. Optionally scope the binding to a specific project

Create Role Binding modal

For more information about roles and permissions, see the User Roles documentation.

Step 4: Generate a Token​

  1. Return to the Service Accounts section
  2. Find your service account and click on it to view details
  3. In the Tokens section, click Create Token
  4. Enter a descriptive name for the token
  5. Click Create Token

Service Account Tokens section

Upon successful creation, the token will appear in a text box. The token value can be copied by clicking on the text box.

danger

The token is only shown once during creation. Make sure to copy and save it in a secure location (e.g., a password manager or secrets management system). If you lose the token, you'll need to create a new one.

Token generated successfully

Token Format​

Service account tokens follow the format: psc_v1_<64-hex-characters>

Managing Tokens​

A record of each token created for a service account appears in the tokens table. You can:

  • View token metadata (name, creation date, last used date)
  • Delete tokens that are no longer needed

Note: Only the cryptographic hash of each token is stored. The actual token value cannot be retrieved after creation.

Service Account Quotas​

  • Maximum 50 service accounts per organization
  • Maximum 100 tokens per service account

Using the Service Account Token​

The Polar Signals Agent is an always-on sampling profiler used to capture raw profiling data. It can discover targets to profile through Kubernetes or systemd. When set up on a Kubernetes node, the Polar Signals Agent can discover containers in that node and continuously send profiles from these containers to the Polar Signals Cloud. Similarly, when set up using systemd, the Polar Signals Agent can discover systemd units on the node the agent is running on.

Authentication with Service Account Tokens​

When using service account tokens, you need to provide two pieces of information:

  1. Token: The service account token via the --remote-store-bearer-token-file flag
  2. Project ID: The project ID via the --remote-store-grpc-headers flag with the key projectID

The token is sent in the Authorization: Bearer header, while the project ID is sent as gRPC metadata.

Example Setup​

First, save your service account token to a file:

echo "psc_v1_a1b2c3d4e5f6..." > /path/to/token.txt

Then, run the Polar Signals Agent:

sudo parca-agent \
  --node=production-node-1 \
  --log-level=info \
  --remote-store-bearer-token-file=/path/to/token.txt \
  --remote-store-grpc-headers=projectID=6fbb6403-203d-4ab1-b48c-6dfbfc67a679

Replace:

  • /path/to/token.txt with the path to your token file
  • 6fbb6403-203d-4ab1-b48c-6dfbfc67a679 with your actual project ID (found in your project settings)

Kubernetes Deployment​

When deploying to Kubernetes, the token is typically stored as a Secret and mounted as a file, while the project ID is provided via command-line arguments in the DaemonSet configuration. See the Kubernetes Setup guide for detailed instructions.

Upon successful execution, the agent will capture profiles and send them to the Polar Signals Cloud. For more information on the Polar Signals Agent and how to explore collected data, see: Kubernetes, systemd.