Best API Practices for Integration with Security Tools
Article written by the Research team at Tenchi Security.
In recent months, we’ve received numerous requests to integrate SaaS applications with Zanshin, Tenchi Security’s third-party cyber risk management solution. We strive to support these integrations, but sometimes we run into issues that tend to make this work difficult - or even impossible. For example, unlike other solutions, we only use APIs that allow assigning roles without granting read or write access to sensitive data.This limitation has prevented us from integrating with certain products in the past.
The issues mentioned also introduce risks and hinder important advancements in global cybersecurity infrastructure, such as the automation and centralization of security controls and visibility across the supply chain. Organizations with access to multiple accounts of a service through its API, such as CSPMs and other security tools, can become high-value targets for attackers if those connections are not established securely.
That’s why we’ve gathered, in this article, some best practices for designing and creating APIs from the standpoint of integration with security tools. However, these are not “requirements” specific to security tools, but rather sensible practices that should always be followed. If your SaaS application implements the tips we share here, it will be more secure - and much easier to integrate with Zanshin.
Best Practices for a Modern API
Granular Access Scopes
At Tenchi Security, we have a non-negotiable design principle for our solution Zanshin - it must not introduce relevant risk to the environments being assessed. In short, even if Zanshin is compromised, this should not result in data breaches or compromise the security of the tested environments.
We adhere strictly to the principle of least privilege. Integrations are only developed when we can guarantee read-only access - and even then, access is limited exclusively to metadata (e.g., configuration details), not the business data stored in the environment. For instance, we should be able to list databases in an IaaS environment and assess their configurations: Are they exposed to the internet? Is logging enabled? Is encryption applied in transit and at rest? Are software updates current? However, at no point should we have access to the actual data within these databases, such as personal information, financial records, or medical data.
We've come across several APIs that provide only unrestricted administrative access across all services, without any option for access control. In such cases, any automation could inadvertently leak or delete data due to a technical failure or malicious activity.
It’s also important to avoid grouping too many actions under a single permission, especially if they involve different levels of access. For example, it is not acceptable for the most basic permission in a service to allow modifications. In general, the more granular the scopes and permissions available, the better.
Another key distinction is between reading sensitive data (like business data, PII, disk contents) and reading configuration or metadata (IAM settings, instance metadata, etc.), which are used for different purposes.
For example, GitHub allows you to create tokens with granular permissions, selecting read and/or write access for specific services:
On the other hand, FreshDesk’s API only allows authentication via user API keys, and only four predefined, immutable scopes exist. This makes it impossible to block access to sensitive data.
One effective way to reduce excessive permissions granted to API users is to clearly indicate which scopes are missing when a request fails due to insufficient permissions. For example, if a user tries to view a firewall rule without the required access, the API should return an error like: “Unauthorized access – missing scopes x, y, and z for this action.” Without this feedback, users often resort to granting broad or unnecessary permissions just to get the request to work.
Finally, we recommend providing at least one method for retrieving the current user's access scopes. When enforcing least privilege access in external environments, it's crucial to verify that the granted permissions are accurate - neither excessive nor insufficient.
API Authentication Methods
Choosing appropriate authentication methods for your API is fundamental to minimize risks and simplify access management.
The most common API authentication methods are:
Tokens or Keys: A piece of text, called token or key, is generated and used as a “password” to access the API. The token’s creator defines its associated permissions.
Access via external account: Access is granted to service accounts managed by other organizations. The organization’s admin sets the account’s permissions in their environment, while the service account owner decides how to manage and use the account’s credentials.
OAuth: An open authorization protocol that enables applications to access a user's data on another service without requiring the user to share their login credentials.
Among these, we recommend OAuth, for the following reasons:
Tokens are simple but can be easily copied or stored insecurely, increasing the risk of credential leakage. Managing them can also become complex without careful documentation of their purpose and storage locations. Additionally, they require regular rotation - which is often a manual and complex process.
External account access is slightly better, but when a service needs to connect to multiple environments (which is common for security tools), either all access is centralized into one account or one account is created per environment - neither of which is ideal. Also, there's no guarantee that the external account owner is managing and using its credentials securely.
OAuth, in contrast, is an open, mature and widely adopted protocol. The permission scope is defined by the application and approved by the user, and can only change with a new approval; This ensures that users cannot accidentally grant incorrect permissions. Additionally, OAuth credentials have short lifespans, which reduces the impact of key leaks. Integration details are also centralized, making it easier to review existing integrations and their associated permissions.
API Service Coverage
Many APIs only offer access to a subset of the data or services available through the platform’s UI.
For example, it’s common for us to find platforms where it is possible to view security settings in the browser, but not through the API.
It’s important to align the UI and the API so both provide the maximum possible overlap in visibility and controls. A lack of API support for certain services affects not only security tools like Zanshin, but also other automations such as data extraction routines and centralized reporting - or management and monitoring tools.
Another key point is that objects should show the same information in both the API and the UI. For example, if the UI displays an object's creation date, the API should also return it, as this information may be important for automation or auditing purposes. Conversely, if the API exposes a server's version, it should also be displayed in the UI. Fragmented information may force users to collect data both from the API and UI to get a full picture - which is not great in terms of user experience.
Finally, it’s also a good idea to unify all your platform’s APIs under a single API. This allows a single key to access all services, if desired. We've encountered platforms where individual services have separate APIs that require independent authentication. These divisions often stem from incomplete mergers, where a company acquires or resells a service but doesn’t unify its API with the existing platform.
This fragmentation hinders a unified view of the platform and leads to the same issues discussed above.
Best Practices for Platform Administrators
Additionally, we’ve included a few tips for those responsible for managing cloud/SaaS platforms and their integrations:
Don’t Store Sensitive Information in Metadata
Fields like object names (instances, databases), tags, or comments may be loosely restricted or even public. Avoid putting confidential data in these fields.
For example, don’t name an instance “merger-project-with-company-x” if the project is secret. Don’t leave a disk comment like “used on instance x, password 123456”. Instead, use code names for sensitive projects, store authentication info like passwords in secure vaults, and fix these mistakes as soon as you identify them.
Review and Sanitize Your Integrations
Not every integration lasts forever. Over time, your organization may stop using certain services or end partnerships. That’s why it’s important to regularly review your active integrations and the access permissions they have. Removing unnecessary access helps reduce your organization’s risk exposure.
And like all access review tasks, the less often you do it, the more painful and time-consuming each revision becomes.
To assist with this, maintain documentation of your existing integrations. At a minimum, record the purpose of each integration and the point of contact within your organization.
Keep an Up-to-Date API Key Inventory
As mentioned, some integrations use API keys - which can be used by anyone who has them, and can be easily copied or shared incorrectly, and should be regularly rotated.
To mitigate these risks, keep an updated inventory of all API keys generated and used by your platform. Important information to log includes: the reason for creating the key, who requested it (internally), where and how it’s used, its permissions, and the date of its last rotation.
In the event of a key leak, this information will be critical to ensure a fast and effective incident response.
