Overview
The Hub Token module handles JWT-based authentication token retrieval and validation for the Guardrails Hub API service.
Description
This module provides the get_jwt_token function, which reads a stored JWT token from the Guardrails RC configuration object, validates its expiration and integrity, and returns it for use in authenticated Hub API requests. The module defines custom exception classes (AuthenticationError, ExpiredTokenError, InvalidTokenError, HttpError) for fine-grained error handling. The VALIDATOR_HUB_SERVICE constant resolves the Hub API endpoint from an environment variable (GR_VALIDATOR_HUB_SERVICE) with a default fallback. Token validation is performed using the pyjwt library with signature verification disabled, focusing solely on expiration checks.
Usage
Use this module when you need to authenticate requests to the Guardrails Hub API. It is called internally by validator inference and hub telemetry components to obtain a valid bearer token. Consumers should handle ExpiredTokenError and InvalidTokenError to prompt users to re-authenticate via guardrails configure.
Code Reference
Source Location
- Repository: Guardrails
- File:
guardrails/hub_token/token.py
Signature
VALIDATOR_HUB_SERVICE: str
class AuthenticationError(Exception): ...
class ExpiredTokenError(Exception): ...
class InvalidTokenError(Exception): ...
class HttpError(Exception):
status: int
message: str
def get_jwt_token(rc: RC) -> Optional[str]
Import
from guardrails.hub_token.token import get_jwt_token, VALIDATOR_HUB_SERVICE
from guardrails.hub_token.token import AuthenticationError, ExpiredTokenError, InvalidTokenError, HttpError
I/O Contract
get_jwt_token
| Parameter |
Type |
Description
|
rc |
RC |
The Guardrails RC configuration object containing the stored token
|
| Returns |
Type |
Description
|
| Token |
Optional[str] |
The valid JWT token string, or None if no token is configured
|
| Raises |
Description
|
ExpiredTokenError |
Raised when the JWT token has expired; message instructs user to run guardrails configure
|
InvalidTokenError |
Raised when the JWT token cannot be decoded; message instructs user to run guardrails configure
|
Constants
| Constant |
Type |
Description
|
VALIDATOR_HUB_SERVICE |
str |
The Guardrails Hub API endpoint, read from GR_VALIDATOR_HUB_SERVICE env var (default: https://hub.api.guardrailsai.com)
|
FIND_NEW_TOKEN |
str |
User-facing message with URL to obtain a new token
|
TOKEN_EXPIRED_MESSAGE |
str |
User-facing error message for expired tokens
|
TOKEN_INVALID_MESSAGE |
str |
User-facing error message for invalid tokens
|
Usage Examples
from guardrails.classes.rc import RC
from guardrails.hub_token.token import get_jwt_token, ExpiredTokenError, InvalidTokenError
rc = RC.load()
try:
token = get_jwt_token(rc)
if token:
headers = {"Authorization": f"Bearer {token}"}
# Use headers for Hub API requests
except ExpiredTokenError:
print("Token expired. Please run: guardrails configure")
except InvalidTokenError:
print("Token invalid. Please run: guardrails configure")
Related Pages
Page Connections
Double-click a node to navigate. Hold to expand connections.
