ApiKee 1.0.8

ApiKee .NET

ApiKee is a lightweight and easy-to-use .NET library for managing and securing your API endpoints. Whether you want to validate API keys locally or via a server, ApiKee ensures smooth integration with minimal configuration. This library is also compatible with Swagger, providing additional security to your API documentation.

Table of Contents

1. Concept Overview
2. Getting Started
3. Usage
   • Local Validation
   • Server Validation
4. Protecting Swagger
5. Server Validation Options
   • Build Your Own Server
   • Use ApiKee Premium Server
6. Contribution
7. License

Concept Overview

ApiKee is built around the idea of API key-based security, providing two main ways to validate requests:

1. Local Validation:

   • Check requests locally using a predefined key.
   • The key can be stored in:
     • App settings.
     • Environment variables.
     • A database.

2. Server Validation:

   • Validate requests by sending them to a central server.
   • Supports:
     • Your own custom server.
     • ApiKee Premium Server (with a dashboard and analytics at apikee.com).

Getting Started

1. Install the ApiKee NuGet package:

   dotnet add package ApiKee
   

2. Add ApiKee to your Program.cs or Startup.cs.

3. Protect your controllers or endpoints by adding the [ApiKee] attribute.

Usage

1. Local Validation

Local validation checks the API key locally without involving any external server.

How It Works

• A request must include the header X-Api-Key with a valid key.
• The key is validated against a value stored in:
  • App settings.
  • An environment variable.
  • A database.

Setup

1. Add API Key to App Settings:

   {
     "ApiKee": {
       "LocalKey": "your-local-api-key"
     }
   }
   

2. Configure in Program.cs:

   var builder = WebApplication.CreateBuilder(args);
   
   // Load configuration
   var apiKeeSection = builder.Configuration.GetSection("ApiKee");
   var apiKeeConfig = new ApiKeeConfig
   {
       LocalKey = apiKeeSection["LocalKey"]
   };
   ApiKee.Extensions.ApiKeeConfiguration.ConfigureApiKee(apiKeeConfig);
   
   // Add services
   builder.Services.AddControllers();
   builder.Services.AddApiKee();
   builder.Services.AddApiKeeSwagger();
   
   var app = builder.Build();
   
   app.UseSwagger();
   app.UseSwaggerUI();
   app.UseApiKee();
   app.MapControllers();
   
   app.Run();
   

3. Protect an Endpoint:

   [HttpGet]
   [ApiKee]
   public IActionResult GetSecureData()
   {
       return Ok("This is a secure endpoint");
   }
   

4. Key Alternatives:

   • Use an environment variable:

     LocalKey = Environment.GetEnvironmentVariable("APIKEE_LOCAL_KEY")
     

   • Retrieve the key from a database:

     LocalKey = GetApiKeyFromDatabase() // Implement your logic
     

2. Server Validation

Server validation sends request details to a central server for validation. This is ideal for dynamic or centralized API key management.

How It Works

• A request must include the header X-Api-Key with a valid key.
• Details like the EndpointId, ProjectId, and Environment are sent to the server for validation.

Setup

1. Add Server Configuration to App Settings:

   {
     "ApiKee": {
       "ServerKey": "your-server-key",
       "ProjectId": "your-project-id",
       "Environment": "staging",
       "ServerUrl": "https://premium.apikee.com"
     }
   }
   

2. Configure in Program.cs:

   var builder = WebApplication.CreateBuilder(args);
   
   // Load configuration
   var apiKeeSection = builder.Configuration.GetSection("ApiKee");
   var apiKeeConfig = new ApiKeeConfig
   {
       ServerKey = apiKeeSection["ServerKey"],
       ProjectId = apiKeeSection["ProjectId"],
       Environment = apiKeeSection["Environment"],
       ServerUrl = apiKeeSection["ServerUrl"]
   };
   ApiKee.Extensions.ApiKeeConfiguration.ConfigureApiKee(apiKeeConfig);
   
   // Add services
   builder.Services.AddControllers();
   builder.Services.AddApiKee();
   builder.Services.AddApiKeeSwagger();
   
   var app = builder.Build();
   
   app.UseSwagger();
   app.UseSwaggerUI();
   app.UseApiKee();
   app.MapControllers();
   
   app.Run();
   

3. Protect an Endpoint:

   [HttpGet]
   [ApiKee("secure-endpoint-id")]
   public IActionResult GetSecureData()
   {
       return Ok("This is a server-validated secure endpoint");
   }
   

Protecting Swagger

The [ApiKee] attribute automatically protects your Swagger documentation. Requests to /swagger will require a valid API key.

To use:

1. Add the middleware in Program.cs:

   app.UseApiKee();
   

2. Provide the API key in Swagger UI:

   • Open Swagger at /swagger.
   • Click Authorize.
   • Add the X-Api-Key header with your API key.

Server Validation Options

1. Build Your Own Server

If you want to build your own server, here’s the expected API structure:

• POST /validate:
  • Request body:

    {
      "EndpointId": "secure-endpoint-id",
      "ApiKey": "provided-api-key",
      "ProjectId": "your-project-id",
      "Environment": "staging"
    }
    

  • Response:

    {
      "isValid": true,
      "message": "Validation successful"
    }
    

2. Use ApiKee Premium Server

Leverage the ApiKee Premium Server at apikee.com to simplify server-side validation. Benefits include:

• A centralized API key management dashboard.
• Request analytics and monitoring.
• Support for multiple projects and environments.

Contribution

Contributions are welcome! If you’d like to improve ApiKee, follow these steps:

1. Fork the Repository: Start by forking the ApiKee repository on GitHub.
2. Create a Branch:

   git checkout -b feature/your-feature-name
   

3. Make Changes: Implement your changes and add appropriate tests.
4. Test Your Code: Ensure all tests pass:

   dotnet test
   

5. Submit a Pull Request: Push your branch and submit a pull request to the main repository.

Ideas for Contribution

• Add new validation methods or sources.
• Improve the documentation or examples.
• Enhance integration with third-party services.

For detailed contribution guidelines, visit the ApiKee GitHub repository. Thank you for helping make ApiKee better!

License

The ApiKee library is released under an open-source license. You are free to use, modify, and distribute the library in compliance with the licensing terms.

• Note: The open-source license applies to the library only.
• For server-side validation, you have two options:
  1. Build your own server: You can implement your own validation server by adhering to the ApiKee specifications. See the API references for more details.
  2. Use the ApiKee Premium Server: ApiKee provides a ready-to-use server and dashboard at apikee.com, which includes additional features like analytics and centralized key management. This is a paid service.

For the full license text, visit the ApiKee GitHub repository.

ApiKee is a powerful and easy-to-use library for securing your API endpoints. Whether you manage API keys locally or prefer a centralized server solution, ApiKee ensures a smooth experience for developers.

For more details or to explore premium features, visit apikee.com.