Let’s Talk About How to Design a Secure External API

When exposing APIs to external services, it is critical to ensure secure communications to prevent unauthorized access and data leakage.

Two commonly used API security methods are Token-based authentication and HMAC (Hash Message Authentication Code)-based authentication.

Below we describe how these two methods work and compare their differences.

01 Token-based

• Step 1 - The user enters the password on the client, which sends it to the authentication server.
• Step 2 - The authentication server validates the credentials and generates a token with an expiration date.
• Step 3 and 4 - Now, the client can send requests and access the server resources by including this Token in the Authorization header of each API request. This access is valid until the token expires.

Advantage

• Stateless: The server does not need to maintain session state, and the Token itself contains all the information required for authentication.
• Flexibility: Tokens can contain metadata such as roles or permissions, supporting fine-grained access control.
• Support OAuth integration: Compatible with OAuth 2.0, suitable for third-party integration scenarios.

Shortcoming

• Token leakage risk: If the token is intercepted, the attacker can abuse it before the token expires, unless other mechanisms (such as token revocation) are in effect.
• Token storage: The client needs to store tokens securely, which can be complex for web or mobile applications.

02 Based on HMAC

The mechanism uses a hash function (SHA256 or MD5) to generate a message authentication code (signature).

• Step 1 and 2 - The server generates two keys, one is the public APP ID (public key) and the other is the API key (private key).
• Step 3: Now we generate an HMAC signature (hmac A) on the client side. This signature is generated based on a set of properties listed in the figure.
• Step 4 - The client sends a request to access the server's resources, including hmac A in the HTTP header.
• Step 5 − The server receives the request containing the request data and the authentication header. It extracts the necessary attributes from the request and generates a signature (hmac B.) using the API key stored on the server side.
• Step 6 and 7 - The server compares hmac A (generated on the client side) with hmac B (generated on the server side). If both match, the requested resource is returned to the client.

Advantage

• Tamper-proof: HMAC ensures that the request has not been tampered with in transit; if even a single byte is changed, the signatures will not match.
• Simple: No token issuance or refresh is required, relying only on shared keys and hash algorithms.
• No risk of token leakage: Since no token can be stolen, this method is inherently safe.

Shortcoming

• Key management: Both the client and the server must securely manage and store the shared key. Once the key is compromised, security is compromised.
• The stateless API is more complex: HMAC does not provide stateless authentication with embedded metadata, and access control needs to be handled separately.

Adding a timestamp to the HMAC signature is to prevent replay attacks. A replay attack is a type of network attack where an attacker intercepts a legitimate request and then re-sends the same request in an attempt to forge an identity or repeat an operation. With the timestamp, the server can verify whether the request is within a reasonable time frame, greatly improving the security of the system.