Configuring Authentication

Zep supports JWT authentication. Carefully follow the instructions below to enable it.

Terminology

JWT

A JWT Token, also known as the Zep API Key, is a JSON Web Token used to authenticate with Zep. Provide this to the Zep SDK when you create a ZepClient instance.

Secret

A cryptographically secure secret is required to sign Zep’s JWT tokens. This secret should be kept safe as access to it may allow access to the Zep API.

Using the zepcli command line utility

1. Download the zepcli CLI tool

Download the zepcli CLI tool from the zepcli releases page. Ensure that you select the right binary for your platform.

Note: The zepcli CLI tool is intended to be used from the command line. If you are using MacOS, you cannot run it from the Finder. You must run it from the Terminal.

2. Generate a secret and the JWT token

A cryptographically secure secret is required to sign Zep’s JWT tokens. This secret should be kept safe as access to it may allow access to the Zep API.

On Linux or MacOS

1
./zepcli -i

On Windows

1
zepcli.exe -i

Carefully copy the secret and JWT token to a safe place. You will need them in the next step.

Note: Do not mix up the secret and the JWT token

The secret is used to sign the JWT token. The JWT token is used to authenticate with Zep. Do not mix up the two! Keep the secret safe. Anyone with access to your JWT token will be able to access your Zep server.

3. Configure Auth environment variables

Set the following environment variables in your Zep server environment:

1
ZEP_AUTH_REQUIRED=true
2
ZEP_AUTH_SECRET=<the secret you generated above>

For development purposes, you can do this in your .env file.

For production, you should set these according to best practices for managing secrets in your deployment environment. For example, Render.com has a environment and secrets management feature that can be used to set these variables.

4. Configure your client SDK to use JWT authentication

You will need to configure your client SDK to use the JWT token you created in Step 2. See the SDK docs for details.

Warning: Implement TLS Encryption

JWT tokens are not encrypted. Your Zep web service should run behind a TLS terminator such as a load balancer. Many cloud providers offer TLS termination on their load balancers. You should check your cloud providers documentation for details on how to configure this.

Keep your JWT token safe. Anyone with access to your JWT token will be able to access your Zep server.

Using another tool

If you’d prefer to use another tool to generate your secret and JWT token, you can do so. Below is an example of how to do so using Python and OpenSSL. Please see the instructions above for correctly setting the Zep environment variables.

1. Generate a secret

A cryptographically secure secret is required to sign Zep’s JWT tokens. This secret should be kept safe as access to it may allow access to the Zep API.

Using OpenSSL (concatenate to remove newlines)

1
openssl rand -base64 64

or using Python

1
import secrets
2
print(secrets.token_urlsafe(64))

2. Generating a JWT token

Most languages have an ecosystem library that supports generation of JWT tokens. Note that Zep uses the HS256 JWT signing algorithm and that no Claims are required. The token must be signed with the same secret that you set in the ZEP_AUTH_SECRET environment variable.