API Keys

​

API Key Advantages

• Programmatic access: Enables automated workflows and scripts to interact with Prowler App.
• Long-lived authentication: Allows optional expiration dates, with a default of 1 year.
• Granular control: Supports multiple keys with distinct names and purposes.
• Secure automation: Simplifies safe integration into CI/CD pipelines and infrastructure-as-code tooling.

​

How It Works

1. API keys are created through Prowler App with a user-defined name and optional expiration date.
2. The full API key appears only once upon creation and cannot be retrieved later.
3. Each API key consists of a prefix (visible in the interface) and an encrypted secret portion.
4. Requests include the API key in the header as Authorization: Api-Key <api-key>.
5. The system updates the Last Used timestamp after each authenticated request.
6. API keys automatically inherit the RBAC permissions of the creator (see Permission Inheritance).
7. Revocation immediately disables an API key and prevents further access.

​

Example curl Request

1. Define the API key as an environment variable to avoid exposing the secret in shell history.
2. Call the desired endpoint with curl and supply the Authorization header.

export PROWLER_API_KEY="pk_example_redacted"

curl -X GET \
  -H "Authorization: Api-Key ${PROWLER_API_KEY}" \
  -H "Content-Type: application/vnd.api+json" \
  https://api.prowler.com/api/v1/tenants

​

Required Permissions

​

Creating API Keys

1. Navigate to Profile → Account in Prowler App.
2. Select the Create API Key button.
3. Configure the API key settings:
   • Name: Provide a descriptive label with at least 3 characters (examples: “CI Pipeline Production”, “Monitoring Script”).
   • Expiration Date (optional): Set a custom expiration date. When omitted, the key expires automatically 1 year (365 days) after creation.
   
4. Select Create API Key to generate the key.
5. Important: Copy and securely store the API key immediately. The full value appears only once and cannot be retrieved later.

​

Managing API Keys

​

Viewing API Keys

1. Navigate to Profile → Account.
2. Review the list of API keys, which includes:
   • Name: The descriptive label assigned to the key.
   • Prefix: The visible portion of the key for identification (for example, pk_ABC12345).
   • Email: The email address of the creator.
   • Created: The timestamp when the key was created.
   • Last Used: The timestamp of the most recent successful authentication.
   • Expires: The configured expiration date.
   • Status: Whether the key is active or revoked.
   

​

Updating API Keys

1. Locate the target API key in the list.
2. Select Edit name from the action menu.
3. Update the available field:
   • Name: Modify the descriptive label for clearer identification.
4. Review the fields that cannot be changed:
   • Prefix, expiration date, and the secret itself remain immutable.
   • Adjusting those properties requires creating a new API key and revoking the existing one.
5. Select Save to apply the change.

​

Actions

​

Permission Inheritance

​

How Permission Inheritance Works

• Current permissions apply: When an API key is used, it operates with the creator’s current RBAC permissions.
• Dynamic updates: Permission changes on the creator immediately propagate to every associated API key.
• User downgrade: Reduced user permissions result in reduced API key capabilities.
• Tenant removal: Removing a user from a tenant automatically revokes every key for that tenant.
• User deletion: Deleting a user from the application automatically revokes all associated API keys.

​

Best Practices for Permission Management

• Use service accounts for automation: Create dedicated user accounts for API-based automation to separate human and programmatic access, ensuring continuity when team members transition.
• Review API key ownership regularly: Confirm that API keys remain associated with appropriate user accounts and document ownership.
• Monitor permission changes: Track user permission updates because every change affects associated API keys.
• Plan for user offboarding: Provision replacement API keys under service accounts before removing users to avoid disruptions.

​

Security Best Practices

​

Key Storage and Management

• Never commit API keys to version control: Add them to .gitignore and rely on environment variables or secure secret management systems.
• Use secret managers: Store keys in AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, GitHub Secrets, or equivalent solutions.
• Rotate keys regularly: Create new keys and revoke old ones on a scheduled basis as part of standard security hygiene.
• Set expiration dates: Enforce automatic rotation and reduce risk by applying expiration dates.
• Monitor last used timestamps: Review usage data to identify unused or potentially compromised keys.

​

Key Usage

• Create dedicated keys per application: Isolate access by assigning separate keys to services, environments, or purposes.
• Use descriptive names: Label keys clearly, such as “ci-pipeline-prod”, “monitoring-staging”, or “terraform-automation”.
• Limit key distribution: Share keys only with team members who require access.
• Revoke immediately on breach: Replace exposed or compromised keys without delay.

​

Environment Variables

​

CI/CD Integration Best Practices

• Use pipeline secrets: Store keys in the CI/CD platform’s secret management system.
• Mask in logs: Ensure the platform masks API keys in build and deployment logs.
• Create pipeline-specific keys: Issue separate keys for each pipeline or environment (development, staging, production).
• Set shorter expirations: Apply shorter expiration periods (for example, 90 days) to enforce rotation.
• Use service accounts: Create dedicated user accounts for CI/CD pipelines (see Permission Inheritance for automatic revocation details).

​

Troubleshooting

​

Authentication Fails with “Invalid API Key”

• Verify that the API key is copied correctly with no extra spaces, line breaks, or hidden characters.
• Ensure the key has not been revoked by checking the Revoked column in the API Keys list.
• Confirm that the key has not expired by reviewing the expiration date.
• Confirm that the correct API key format is in use, including both prefix and secret portions.
• Verify that the key prefix matches what is displayed in Prowler App.

​

API Key Not Working After Creation

• Verify that the full API key was copied from the creation dialog, including both the prefix and encrypted portions.
• Check that the key has not expired by reviewing the expiration date in the management interface.
• Ensure the key is not revoked by reviewing its status in the API Keys list.
• Confirm that authentication targets the correct Prowler API environment.

​

Last Used Timestamp Not Updating

• The timestamp updates only on successful authentication requests.
• Authentication failures prevent the timestamp from updating.
• Verify that requests complete successfully and do not return authentication errors.
• Check that the request reaches the Prowler API and is not blocked by network policies.

​

Need to Retrieve a Lost API Key

• API keys cannot be retrieved after the creation dialog closes for security reasons.
• Create a new API key to replace the lost one.
• Update all applications and scripts that rely on the old key with the new value.
• Revoke the old key after confirming that the new key works to prevent security issues.
• Consider using a secret management system to avoid future loss.

​

Key Was Exposed or Compromised

1. Immediately revoke the compromised key through the API Keys management interface.
2. Review recent activity for unauthorized access using the Last Used timestamp.
3. Create a new API key with a different name to replace the compromised one.
4. Update all legitimate applications with the new key.
5. Investigate the exposure to prevent similar incidents.
6. Implement additional security measures or rely on service accounts for better isolation.