Authentication

LitServe enables authentication to prevent unauthorized access and ensure that only authorized clients can interact with the deployed API.

Background

What is authentication?

Authentication is the process of verifying the identity of a client attempting to access a server. In the context of APIs, this typically involves the client providing credentials, such as an API key, which the server validates before granting access.

When to use authentication?

Authentication is crucial for securing APIs, especially in environments where sensitive data is processed or where access needs to be restricted. By implementing authentication, you can ensure that only clients with valid credentials can interact with your API, protecting your service from unauthorized use and potential abuse.

HTTP Bearer

HTTP Bearer authentication (commonly referred to as Bearer authentication) is a type of token-based authentication scheme. In this approach, the client provides a security token (often a JSON Web Token, or JWT) in the HTTP Authorization header when making a request to a server.

Here’s a simple example of how an HTTP request with Bearer authentication looks:

GET /resource HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>

Enable authentication

To secure your API with authentication using LitServe, follow these two steps:

1. Define the API key as an environment variable (LIT_SERVER_API_KEY).
2. Configure the client to send the API key in its request headers.

This section provides detailed instructions for both the server and the client.

Server

To secure the API with an API key, define the environment variable LIT_SERVER_API_KEY when starting the server. Here's a toy server as example:

import litserve as ls

class SimpleLitAPI(ls.LitAPI):
    def setup(self, device):
        self.model = lambda x: x**2

    def decode_request(self, request):
        return request["input"]

    def predict(self, x):
        return self.model(x)

    def encode_response(self, output):
        return {"output": output}

if __name__ == "__main__":
    api = SimpleLitAPI()
    server = ls.LitServer(api)
    server.run()

Use the LIT_SERVER_API_KEY environment variable when starting the server:

LIT_SERVER_API_KEY=A_SECRET_KEY python server.py

Client

Clients must authenticate using the same API key by including it in the X-API-Key HTTP header of their requests. Any request to server without the correct X-API-Key will result in an unauthorized error.

import requests

# Define the API key in the request headers
headers = {"X-API-Key": "A_SECRET_KEY"}

response = requests.post("http://127.0.0.1:8000/predict", json={"input": 4.0}, headers=headers)
print(response.json())

Advanced custom authentication

To set up advanced custom authentication in LitServe using OAuth or HTTP Bearer, follow these steps:

1. Implement the authorize method in LitAPI to handle custom authentication.
2. Configure the client to send authentication credentials.

Server

To secure the API with Bearer token authentication, the authorize method validates the token. A valid token is "1234." If an invalid token is provided, the server will return a 401 Unauthorized error.

from fastapi import Depends, HTTPException
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer

from litserve import LitAPI, LitServer

class SimpleAuthedLitAPI(LitAPI):
    def setup(self, device):
        self.model = lambda x: x ** 2

    def decode_request(self, request):
        return request["input"]

    def predict(self, x):
        return self.model(x)

    def encode_response(self, output):
        return {"output": output}

    def authorize(self, auth: HTTPAuthorizationCredentials = Depends(HTTPBearer())):
        if auth.scheme != "Bearer" or auth.credentials != "1234":
            raise HTTPException(status_code=401, detail="Bad token")

if __name__ == '__main__':
    api = SimpleAuthedLitAPI()
    server = LitServer(api)
    server.run()

Client

This client sends a POST request to the server with a JSON payload. The request includes a Bearer token ("1234") in the headers for authentication.

import requests

# Define authorization in the request headers
headers = {"Authorization": "Bearer 1234"}

response = requests.post("http://127.0.0.1:8000/predict", json={"input": 4.0}, headers=headers)
print(response.json())