Replacing Individual API Tokens With Team-Owned Credentials in Heroku

API tokens are often created during application setup and then used for months or even years without much attention. A developer creates a token, adds it to a CI/CD pipeline, connects a monitoring service, or uses it in an automation script. Everything works, so nobody thinks about changing it.

The problem usually appears when that developer leaves the company, changes roles, or loses access to the Heroku account.

An integration that depends on that person's credentials may stop working. The remaining team members may not even know which services are using the token or who originally created it.

Heroku introduced Team Authorizations to address this problem. Instead of connecting integrations to an individual account, teams can create API authorizations that belong to the team itself.

This makes credential ownership easier to manage and reduces the dependency on individual team members.

In this article, we will look at how Heroku Team Authorizations work, how to replace individual API tokens, and how to manage team-owned credentials in existing applications and automation workflows.

Why Individual API Tokens Become a Problem

Consider a development team managing several applications on Heroku.

One developer creates a personal API token and uses it for:

Automated deployments.
CI/CD pipeline integration.
Application monitoring.
Infrastructure automation.
Custom scripts that communicate with the Heroku Platform API.

Initially, everything works as expected. The problem starts when the developer leaves the organization.

If the personal token is revoked or becomes unavailable, the integrations depending on it may fail.

Even when the token continues working, the organization has a different problem: it is still dependent on credentials owned by someone who is no longer responsible for the system.

This creates several operational risks.

Difficult Employee Offboarding

Removing a developer from a Heroku team does not automatically give the organization a complete inventory of every external integration using that developer's personal credentials.

Administrators need to identify which automation processes depend on the credentials and update them before access is removed.

Limited Credential Visibility

Personal API tokens are associated with individual accounts. Other team administrators may not have a centralized view of every integration using those tokens.

This makes security reviews and credential audits more difficult.

Unnecessary Operational Dependency

A deployment pipeline should not depend on the continued employment or account status of one developer.

Infrastructure automation belongs to the organization or team responsible for maintaining it.

This is the main reason team-owned credentials are useful.

What Are Heroku Team Authorizations?

Heroku Team Authorizations allow team administrators to create and manage API authorizations that belong to a Heroku Team rather than an individual account.

Introduced in September 2026, this feature provides centralized management of team-owned API tokens and authorized applications.

There are two important types of team authorizations.

1. Direct Authorizations

Direct authorizations provide API tokens for scripts, automation, CI/CD pipelines, and other integrations that need to communicate with the Heroku Platform API.

These tokens belong to the team instead of the administrator who creates them.

For example, a team can create a dedicated authorization for its deployment pipeline.

If the administrator who created the authorization later leaves the team, the credential remains associated with the team.

Team-owned direct authorization tokens have a maximum lifetime of one year. Their secret values are displayed only once during creation, so they must be stored securely.

2. Authorized Applications

Authorized Applications use OAuth to grant third-party applications access to Heroku resources.

For example, a monitoring platform may request permission to access application information through the Heroku Platform API.

During the authorization process, a team administrator can select the team as the owner of the authorization instead of attaching it to a personal account.

This makes the integration easier to manage when team membership changes.

Individual API Tokens vs Team-Owned Credentials

The main difference is credential ownership and management.

Area	Individual API Token	Team Authorization
Ownership	Individual account	Heroku Team
Employee offboarding	May affect dependent integrations	Not tied to the creator's membership
Management	Associated with personal account	Managed through team settings
Visibility	Individual authorization management	Centralized team authorization management
Token lifetime	Depends on authorization type	Team direct tokens expire within one year
Revocation	Managed by the token owner or authorized administrator	Team administrators can revoke
Integration continuity	Depends on individual credential lifecycle	Designed for team-level continuity

Team ownership does not mean that every team member automatically receives access to the token. Administrators still need to control who can create, manage, and use credentials.

Creating a Team-Owned API Token in Heroku

Let's look at a practical example.

Assume your team has a Heroku application named company-api. A CI/CD pipeline needs permission to communicate with the Heroku Platform API during deployment.

Instead of using a developer's personal token, create a team authorization.

Step 1: Verify Team Administrator Access

Only Heroku team administrators can create and manage team authorizations.

Open the team's Settings section and locate Team Authorizations.

This section provides access to team-owned API tokens and authorized applications.

Step 2: Create an Authorization Using the Heroku CLI

You can also create a direct authorization from the Heroku CLI.

Use the following command:

heroku authorizations:create \
  --team=company-team \
  --description="Production CI/CD deployment"

Replace company-team with your actual Heroku team name.

The description should identify the system or integration that will use the token.

For example, use separate descriptions for production deployment, staging deployment, and monitoring integrations.

This makes it easier to understand why a credential exists during future security reviews.

Step 3: Store the Generated Token Securely

After creating the authorization, Heroku displays the token.

Copy it immediately and store it in a secure secrets management system.

Do not save it in source code, commit it to Git, or share it through ordinary team messages.

The token value is shown only once during creation. If you lose it, you will need to regenerate the authorization.

Step 4: List Existing Team Authorizations

You can inspect the authorizations associated with a team using:

heroku authorizations --team=company-team

This helps administrators review the available team-owned authorizations.

Maintain meaningful descriptions so that administrators can distinguish between credentials used by different systems.

Step 5: Verify the Authorization

Before using the token in production, verify that the intended integration can access the required team resources.

Also confirm that it cannot perform operations outside the intended scope.

Team authorizations are designed for team resources such as applications, add-ons, and spaces. They cannot perform user-only actions.

Using Team-Owned Credentials in a CI/CD Pipeline

Creating a team authorization is only part of the implementation. The next step is to connect it to your existing automation.

For example, consider a GitHub Actions workflow that needs to authenticate with Heroku.

Instead of storing a developer's personal API token, store the team-owned token as a repository or environment secret.

Assume the secret is named HEROKU_API_KEY.

A simplified workflow could look like this:

name: Deploy to Heroku

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install Heroku CLI
        run: |
          curl https://cli-assets.heroku.com/install.sh | sh

      - name: Authenticate with Heroku
        env:
          HEROKU_API_KEY: ${{ secrets.HEROKU_API_KEY }}
        run: |
          heroku auth:whoami

      - name: Deploy application
        run: |
          git push heroku main

This example illustrates secret injection and authentication. A real deployment workflow must also configure the correct Heroku Git remote, application access, and deployment strategy.

The important point is that the token is supplied through a protected CI/CD secret rather than being written directly into the workflow file.

When the team needs to rotate the credential, administrators can update the secret without changing the application source code.

Managing OAuth Integrations With Team Authorizations

Not every Heroku integration uses a direct API token.

Some third-party services use OAuth to request access to Heroku resources.

For these integrations, team administrators can authorize an application on behalf of the team.

The general process is:

Start the OAuth authorization flow from the third-party application.
Sign in to Heroku if required.
Review the permissions requested by the application.
Select the appropriate Heroku team when prompted.
Complete the authorization.
Verify that the application appears under the team's authorized applications.

The OAuth integration continues to be associated with the team rather than the administrator who completed the authorization.

This is particularly useful for monitoring platforms and external services that need ongoing access to team-owned applications.

How to Rotate or Revoke Team Authorizations

Credential rotation is an important part of maintaining secure integrations.

Heroku allows team administrators to regenerate or revoke team-owned authorizations.

Regenerating a Token

Regeneration replaces the existing token value.

You can regenerate an authorization from the Team Authorizations section in the Heroku Dashboard.

After regeneration, the previous token becomes invalid immediately.

Before performing this operation, identify every service using the existing credential.

A safe rotation process is:

Identify all integrations using the token.
Generate the replacement authorization.
Store the new token in the secrets management system.
Update the dependent integrations.
Verify that authentication and required operations work.
Confirm that no services still depend on the previous token.

Do not regenerate a production token without coordinating the update across dependent systems.

Revoking a Token

If an authorization is no longer required or may have been exposed, revoke it.

You can do this from the Team Authorizations section in the Dashboard.

Revocation immediately and permanently disables the authorization. Any integration using that token will stop working.

Regeneration and revocation should therefore be treated as controlled operational changes.

Best Practices for Managing Heroku Team Credentials

Moving to team-owned credentials improves ownership, but teams still need a clear credential management process.

Create Separate Credentials for Different Integrations

Avoid using one token for every deployment pipeline, monitoring service, and automation script.

Create separate authorizations with meaningful descriptions.

If one integration is compromised, administrators can revoke its credential without unnecessarily affecting unrelated systems.

Set an Expiration and Rotation Schedule

Team direct authorization tokens can have expiration periods of 30, 60, 90 days, or one year.

Choose an expiration period based on the sensitivity of the integration and your organization's security requirements.

Do not wait until a token expires to discover which services depend on it.

Apply Least-Privilege Access

Grant only the access required by the integration.

A deployment process does not necessarily need the same permissions as an infrastructure administration script.

Review the available scopes and team authorization limitations before assigning access.

Keep Secrets Outside the Repository

Store credentials in a CI/CD secret store or an approved secrets management platform.

Never commit API tokens to Git repositories or include them in application logs.

If a token is accidentally exposed, revoke it and investigate its possible use.

Maintain an Authorization Inventory

Keep a record of:

Authorization description.
Owning team.
Integration or service using it.
Creation date.
Expiration date.
Responsible team.
Rotation status.

This makes security reviews and employee offboarding much easier.

Common Mistakes When Moving to Team-Owned Credentials

Mistake	Why it causes problems	Recommended approach
Reusing one token everywhere	Makes rotation difficult	Create separate credentials for each integration
Saving tokens in Git	Exposes credentials to repository users	Use protected secrets
Forgetting token expiration	Integrations may unexpectedly stop working	Track expiration dates
Regenerating without preparation	Existing integrations immediately lose access	Coordinate credential rotation
Granting excessive permissions	Increases the impact of credential exposure	Apply least privilege
Ignoring OAuth authorizations	Third-party integrations may remain tied to personal accounts	Review authorized applications
Not documenting credentials	Makes future maintenance difficult	Maintain an authorization inventory

Advantages and Disadvantages

Advantages

Credentials belong to the team rather than an individual developer.
Integrations are less dependent on employee account changes.
Administrators get centralized visibility into team authorizations.
Token rotation and revocation can be managed at the team level.
Separate credentials can be created for different automation processes.
OAuth integrations can also be authorized on behalf of a team.

Disadvantages

Existing integrations need to be migrated from personal credentials.
Token rotation can interrupt services if not coordinated properly.
Team administrators need to manage authorization permissions and expiration.
Team authorizations cannot perform user-only actions.
Teams must maintain secure storage and credential inventory processes.

Summary

Individual API tokens can become an operational risk when important integrations depend on credentials owned by a single developer. Employee departures, account changes, and token revocation can interrupt deployments and other automated processes.

Heroku Team Authorizations provide a better ownership model by allowing API tokens and OAuth authorizations to belong to a team rather than an individual account.

Developers can use direct authorizations for CI/CD pipelines and automation scripts, while Authorized Applications support third-party OAuth integrations. Administrators can manage these credentials centrally, review their usage, regenerate tokens, and revoke access when required.

When migrating existing integrations, start by identifying personal tokens currently used by your applications and automation. Replace them with appropriately scoped team-owned credentials, store the new values securely, and verify each integration before removing the old credentials.

The goal is simple: important infrastructure should depend on team-managed credentials, not on the account of an individual developer.