Overview

This documentation outlines the authentication mechanism used in the application to verify clients via an HTTP header containing an API key. This method ensures that only clients with a valid API key can access certain endpoints of the application.

Authentication Process

The application employs an API key-based authentication scheme where a specific HTTP header, named X-Api-Key, is used to pass a unique key that identifies the client. This key is validated by the application to authenticate the client and grant access to protected resources.

Header Format

The X-Api-Key header must be included in each request to the secured endpoints of the application. The format of the X-Api-Key header is as follows:

X-Api-Key: <api_key>

Here, <api_key> is a placeholder for the actual API key provided to the client upon registration.

API Key Generation

1. Client Registration: When a new API key is requested the application generates a unique API key. This key is typically a long, random string.
2. Key Issuance: The generated API key is sent back to the client and should be stored securely. This key will be used for subsequent requests to authenticate the client.
   N.B.: after the API key has been issued, the system displays it, and it will be the only time the API is visible to you. If lost, a new API key must be generated.

Request Example

To access a protected resource, the client must include the X-Api-Key header with the API key:

GET /api/v1/convert/USD_EUR?amount=200.80
X-Api-Key: abc123xyz456

Error Handling

If the X-Api-Key header is missing, malformed, contains an invalid key, or the monthly quota is exceeded, the application will respond with an appropriate HTTP status code:

• 401 Unauthorized: Indicates that the API key is missing or invalid.
• 403 Forbidden: Indicates that the client is authenticated but does not have permission to access the requested resource.

Example Error Response:

{
    "status": 401,
    "error": "monthly quota exceeded"
}

Best Practices

• Secure Storage: Store the API key securely on the client side, using secure storage mechanisms provided by the platform.
• Key Rotation: Implement API key rotation policies and provide a mechanism to regenerate keys to maintain security.
• Rate Limiting: Apply rate limiting to API key usage to prevent abuse.
• HTTPS: Always use HTTPS to encrypt the transmission of API keys and other sensitive data.

Conclusion

API key-based authentication is a robust method for securing your application endpoints. By following the outlined process and best practices, you can ensure secure and efficient authentication for your clients.