Skip to main content

Migrate Agents to Service Accounts

This guide walks you through migrating your Polar Signals Agent deployments from project tokens to the new IAM system using service accounts with minimal role bindings.

What's Changing​

Previously, agents authenticated using project-scoped JWT tokens. The new IAM system replaces these with:

  • Service accounts — named identities with granular, role-based permissions
  • Service account tokens — API tokens (format: psc_v1_<64-hex-characters>) tied to a service account
  • Role bindings — assignments that grant only the permissions needed

The project to send data to is now specified separately via a projectID gRPC metadata header, rather than being embedded in the token.

Steps​

1. Create a Service Account​

  1. Go to your organization settings
  2. Navigate to IAM > Service Accounts
  3. Click Create Service Account
  4. Enter a descriptive name (e.g., production-agent)

Create Service Account modal

2. Create a Role Binding​

  1. Go to IAM > Role Bindings
  2. Click Create Role Binding
  3. Select your new service account as the subject
  4. Select the Writer role
  5. Optionally, scope the binding to a specific project

Create Role Binding modal

The Writer role grants profile.write and debuginfo.write, which is what agents need by default since they upload both profiling data and debug information extracted from running processes.

tip

If you have explicitly disabled debuginfo uploads on the agent (via --debuginfo-upload-disable), you can use the Profile Writer role instead, which only grants profile.write.

3. Generate a Token​

  1. Go to IAM > Service Accounts and click on your service account
  2. In the Tokens section, click Create Token
  3. Copy the token immediately — it is only shown once

Token generated successfully

4. Update Your Agent Configuration​

Replace the old project token with the new service account token and add the projectID header. The two key flags are:

  • Token: --remote-store-bearer-token (or --remote-store-bearer-token-file for file-based)
  • Project ID: --remote-store-grpc-headers=projectID=<your-project-id>

Find your project ID in your project settings in the Polar Signals Cloud UI.

5. Verify and Revoke​

After restarting the agent, verify profiling data is arriving in Polar Signals Cloud. Then revoke the old project token to complete the migration.

See Also​

  • Generating Tokens — creating service accounts and tokens
  • IAM — roles, permissions, and role bindings reference