Skip to main content

Rotate a Pangea API Token

Learn how to rotate a Pangea API token

Pangea API token rotation enables you to create a new version of a token, replacing the current version. By default, rotating a Pangea API token will result in the "current" version being transitioned to the "destroyed" state. When the current version of the token is transitioned to the "destroyed" state, the Vault service will also delete the token from the token listings.

Manual Rotation​

A Pangea API token can be manually rotated at any time. When manually rotated, the Vault service will provision a new Pangea API token with the same permissions and store it in the Vault on your behalf.

import os

import pangea.exceptions as pe
from pangea.config import PangeaConfig
from pangea.services import Vault


def rotate_token(token_id: str) -> str:
    token = os.getenv("PANGEA_VAULT_TOKEN")
    domain = os.getenv("PANGEA_DOMAIN")
    config = PangeaConfig(domain=domain)
    vault = Vault(token, config=config)

    try:
        # Rotate token.
        retrieve_response = vault.pangea_token_rotate(token_id)

        # Retrieve latest version.
        retrieve_response = vault.get(token_id)
    except pe.PangeaAPIException as e:
        print(f"Vault Request Error: {e.response.summary}")
        for err in e.errors:
            print(f"\t{err.detail} \n")
    else:
        return retrieve_response.result.current_version.secret

Configure a rotation policy​

A Pangea API token rotation policy can be provided at the time of importing a token, or it can be provided as part of a token update. A rotation policy allows you to set an interval over which a token is automatically rotated, with the new token version generated by the Vault service. Rotating a Pangea API token will automatically transition the current version to the "destroyed" state.

The format for rotation interval is <number><units>, with allowed units being "days," "months," and "years."

Pangea API tokens in the Vault have a unique configuration parameter called "grace period." This describes how long after rotation, the Vault service should wait to delete the token to which the Pangea API token Vault item points. See more in the overview.


import os

import pangea.exceptions as pe
from pangea.config import PangeaConfig
from pangea.services import Vault


def configure_token_rotation_policy(token_id, interval, grace_period):
    token = os.getenv("PANGEA_VAULT_TOKEN")
    domain = os.getenv("PANGEA_DOMAIN")
    config = PangeaConfig(domain=domain)
    vault = Vault(token, config=config)

    try:
        # configure rotation policy
        # example rotation frequency "1year"
        # example grace period "5hours"
        vault.update(
            token_id,
            rotation_frequency=interval,
            rotation_grace_period=grace_period
        )

    except pe.PangeaAPIException as e:
        print(f"Vault Request Error: {e.response.summary}")
        for err in e.errors:
            print(f"\t{err.detail} \n")

    return

Was this article helpful?

Contact us