Securing APIs with WSO2 API Manager: A Guide to End-to-End API Security

APIs are the backbone of modern applications, and securing them is essential. WSO2 API Manager provides a comprehensive set of tools to help developers secure APIs, from the gateway to the backend.

What is API security?

API security is the practice of protecting APIs from unauthorized access, abuse, data leaks, and other threats. With WSO2 API Manager, you can ensure that only the correct users and systems can access the right APIs under the right conditions.

Why is API security important?

A single insecure API can expose sensitive data or disrupt critical services. Without robust API security: 

• You risk data breaches (e.g., leaked user details or financial info)
• Attackers may gain unauthorized access to internal services.
• There can be service disruptions that impact users and operations.

WSO2 API Manager gives you the tools to prevent this, while giving you the flexibility to tailor security for internal, partner, or public APIs.

Using a central gateway to apply end-to-end protection

The API Gateway acts as the main entry point to your services, making it the best place to enforce security controls such as authentication, access control, input validation, and traffic management.

In WSO2 API Manager, the gateway also supports:

• Data encryption: All data transmitted through the gateway is protected using HTTPS (TLS).
• OAuth2 token encryption: Encrypts tokens and secrets using the primary keystore to keep sensitive data secure at rest.
• Input validation: Uses schema checks and regex filters to block harmful or invalid requests.

By applying these at the gateway level, you ensure that only secure, trusted, and validated requests reach your backend systems.

Authentication

Authentication is about identifying the user who has requested to access the API and deciding whether to or not to grant access. WSO2 API Manager supports multiple authentication mechanisms as described below.

Basic authentication

This is the simplest authentication method used in an HTTP authentication process, where user credentials are encoded using base64 and attached to an HTTP header when sending a request. While easy to implement, it is recommended only for internal or low-risk APIs. 

Learn how to enable basic authentication

OAuth 2.0

OAuth 2.0 is the most widely used token-based authentication mechanism for securing APIs. Clients obtain access tokens from an authorization server and include them in the request header to authenticate. WSO2 API Manager issues JWT-formatted access tokens by default when applications are created in the Developer Portal.

Let’s discuss some of the commonly used grant types in WSO2 API Manager.

• Authorization code grant

This grant type is a secure option for public clients, such as web applications running on a secure server. It is the most secure flow for obtaining access tokens, as tokens are never exposed to the user’s browser or device. 

Try the authorization code grant

• Password grant

When the client is able to obtain the credentials of the resource owner, which means the resource owner has a trusted relationship with the client, this grant type can be used./

Explore the password grant

• Client credentials grant

Ideal for machine-to-machine authentication, where no end user is involved and the application owner is the resource owner. The client authenticates using its client ID and secret.
Check out the client credentials grant

• Kerberos OAuth2 grant

Works with Kerberos authentication systems, making it suitable for enterprise environments using SSO.

Kerberos OAuth2 grant in WSO2 API Manager

• Refresh token grant

The refresh token grant type is used to obtain a new access token using a previously obtained refresh token. This grant type is typically used in situations where long-lived access to a resource is required.

Try using the refresh token grant

• JWT grant

The JWT grant uses a signed JWT to request an access token without requiring direct user approval. It is useful for trusted systems with pre-established credentials.

Try JWT Grant

OIDC-based authentication

OIDC (OpenID Connect) is an authentication mechanism built on top of OAuth 2.0. It lets you verify who the end-user is and also obtain basic profile information from the authorization server. In WSO2 API Manager, this can be used to obtain basic profile information about the user who generates the access token. Please refer to obtaining user profile information with OpenID Connect for more details.

API key-based authentication

This is the simplest form of application-based security, and it can be easily configured for an API. In WSO2 API Manager’s Developer Portal, an API key can be obtained for a client application via the UI or using REST APIs. 

The API key is simply a string value passed by a client app to the WSO2 API Manager gateway and used to uniquely identify the client app and if the app is valid. This security method is most suitable for internal APIs within the organization. Find out how to secure APIs with API keys.

Mutual TLS (mTLS) Authentication

Mutual SSL, also known as Mutual TLS (mTLS), is a certificate-based authentication, where both the client and server verify each other’s identity using digital certificates issued by the trusted certificate authorities(CAs). It is commonly used for APIs shared with partners or a known group of clients, where high security is required.

Authorization

Once authenticated, authorization is the mechanism to verify whether the authenticated entity is permitted to access the particular resource. WSO2 supports different authorization methods as follows.

Role-based access control

Here, resources can be secured with scopes that are bound to specific user roles. Scopes ensure that only the allowed resources can be accessed by the consumer. If the resource is not allowed for consumption (based on the role of the consumer), then consuming that resource will not be allowed even though there is a valid access token. Visit role-based access control with OAuth scopes to see how you can use this in WSO2 API Manager.

Open policy agent (OPA)

The open policy agent (OPA) is an open source tool used to define and enforce policies as code. It helps make decisions like who can access what, when, and under what conditions.

Imagine you're running an online learning platform. You want only teachers to access the /create-course endpoint, while students should be allowed to access /view-course only during certain hours (e.g., 6 a.m. to 10 p.m.). Instead of hardcoding these rules into your application, you can define them in OPA using a policy file written in Rego.

Transport level security

Transport level security (TLS) is a foundational transport-layer encryption mechanism that applies to all API traffic via HTTPS (HTTP over TLS). TLS is a method of protecting data while it’s being transmitted between systems, like a client and your API Gateway.

WSO2 API Manager applies transport-level security in the following ways.

• All APIs are exposed over HTTPS ports by default.
• Weak ciphers can be disabled to avoid known vulnerabilities. 
• For added security, you can turn off HTTP, WebSocket, and WebHook transports if they are not used

More details: configure transport level security

JSON schema validator

This validates incoming requests and outgoing responses using OpenAPI-defined schemas. WSO2 API Manager uses a built-in handler called swaggerSchemavalidator to validate API requests and response payloads against the defined JSON schema in the OpenAPI definition. When you enable schema validation via the Publisher Portal or a REST API, the swaggerSchemavalidator handler is enabled for the API Synapse configuration file.

Here’s how it works:

• Request validation

• Response validation

Check out how to enable JSON schema validator in WSO2 API Manager

Threat protection

Threat protection is a security feature built into the API Gateway. It is designed to detect and block malicious content in HTTP requests and responses, especially in the payloads. It works using a Gateway Handler, which checks the content of incoming and outgoing messages before they reach the backend services.

As of now, WSO2 API Manager offers three types of protectors for the Gateway.

1. Regular expression threat protection for API gateway

• Protect APIs against attacks like SQL injections using predefined regex patterns. 
• Custom regexes can be added for specific patterns to protect against threats such as JavaScript Injection, Server-side Include (SSI) Injection, XPath Injection, and Java Exception Injection. 

Check out how to apply the regular expression policy in WSO2 API Manager

02. JSON threat protection for API gateway

• Validate the request body of JSON messages, thereby preventing payload attacks. 
• Define limits for string lengths, object depth, array sizes, etc., using the json_validator sequence.

More details available at JSON threat protection

03.XML threat protection for API gateway

• Protect APIs against XML-based attacks by validating incoming XML payloads based on pre-configured limits.
• Implemented via the xml_validator sequence at the gateway level.
• Applies limits such as max depth, element count, and attribute size.
• Supports schema validation using XSDs for each API resource.

More details can be found at XML Threat Protection.

Rate limiting 

Allowing unlimited access to APIs is a poor practice, as it enables consumers to make an unlimited number of requests at any time. This can lead to excessive load on backend services and potential system downtime. To mitigate these issues, WSO2 API Manager supports rate limiting, which can be enforced based on conditions like request count, bandwidth usage, or query complexity.

By applying appropriate rate-limiting policies, you can:

• Prevent DDoS attacks
• Implement usage plans for monetization
• Enforce fair usage across all consumers
• Avoid backend overloading due to spikes and overuse

WSO2 API Manager allows rate limiting to be applied at multiple levels: 

• API-level: Control traffic to specific APIs
• Application-level: Set limits per client application and it will be allocated per user.
• Subscription-level: Define limits per API–app subscription

These policies provide flexibility to control traffic based on your business and operational needs.

Backend rate limiting

In addition to controlling traffic at the API Gateway, WSO2 API Manager also supports backend rate limiting. That means setting limits on the total number of calls a particular

API is allowed to make to the backend. We can set the maximum throughput under rate-limiting settings when publishing the API through UI. Alternatively, you can go to the synapse configuration of the API and specify the maximum backend throughput there.

Discover how to set maximum backend throughput limits

Burst control

Burst control within subscription tiers ensures that consumers don’t exhaust their quota in a short burst. For example, even if an application is allowed 1,000 requests per hour, a burst control limit of 25 requests per minute can be enforced to smooth out traffic. While overall tier limits are cluster-wide, burst control is enforced at the individual gateway node level to manage short-term spikes efficiently.

Check out introducing rate limiting use case

Choosing the right security method: real-world scenarios

Here's a quick guide to help developers decide which security method to use, based on practical scenarios.

Security method	When to use
Basic Authentication	For testing or securing internal development.
OAuth2 - Authorization Code Grant	For public web/mobile apps that need secure user logins.
OAuth2 - Password Grant	For first-party apps where the client is trusted.
OAuth2- Client Credentials Grant	For backend services communicating without user context (e.g., payment service calling inventory API).
OAuth2 - Refresh Token Grant	When long-term access is required without repeated user logins, like mobile apps.
JWT Grant	When an external system issues JWTs and WSO2 API Manager needs to trust them directly.
OIDC (OpenID Connect)	When you need both authentication and basic user profile information.
API Key	For internal low-risk APIs within the organization.
Mutual SSL	For high-security B2B or financial APIs (e.g., partner bank integration)
Role-Based Access Control	To control access to API resources based on user roles.
Open Policy Agent (OPA)	For access control based on rules like user role, time of access, or other conditions.
JSON Schema Validation	To ensure the request and response match the defined schema.
Regex Threat Protection	To block common injection attacks using regex patterns.
JSON Threat Protection	To limit size/depth of incoming JSON.
XML Threat Protection	To protect APIs from malicious or oversized XML payloads.
Rate Limiting	To enforce usage tiers and ensure fair access (e.g., Gold: 5,000 req/min, Silver: 2,000 req/min).
Transport-Level Security (TLS)	To protect data while it's being sent by using HTTPS and stopping others from reading or changing it.

Conclusion

WSO2 API Manager empowers developers to build secure APIs with out-of-the-box features that address threats at every layer

• Authentication and authorization to verify who accesses your APIs and what they can do.
• Rate limiting and throttling to manage traffic and ensure backend stability.
• Threat protection to block malicious payloads and malformed inputs.
• Input validation using schema and regex filtering.

Begin by assessing the sensitivity of your API and determining who needs access. Then, apply the right mix of security features to match those needs. With WSO2, securing APIs becomes an easy and natural part of building and deploying your applications.