Highlights
- Generate long-lived JWT credentials for automated scripts and CI/CD pipelines without exposing primary user passwords to third-party integrations.
- Manage tokens via four core API endpoints (Generate, List, Get, Revoke) documented in Swagger for programmatic integration.
- Implement secure access control with AES-256-GCM encryption, SHA-256 hashing, and immediate token revocation capabilities.
Secure and flexible authentication remains a requirement for modern application development. We are announcing a new feature in FalkorDB Browser: Personal Access Tokens (PATs), powered by JWT authentication and fully documented with OpenAPI/Swagger.
What Are Personal Access Tokens?
Personal Access Tokens are secure, long-lived credentials that allow you to authenticate API requests without exposing your password. You can view them as specialized keys, each with its own name, expiration date, and permissions, that you create, manage, and revoke independently.
If you build automated scripts, integrate FalkorDB into your CI/CD pipeline, or develop third-party applications, Personal Access Tokens provide a secure method to authenticate.
Graphs can turn your tangled security data into a living, interactive map, making it possible to spot risks and answer tough questions in real time.”
— Roi Lipman, CTO & Co-Founder at FalkorDB
Complete Token Management API
We built a comprehensive token management system with four core endpoints:
1: Generate token
POST /api/auth/tokens/credentials
Create a new token with customizable expiration. You set tokens to expire in 30, 60, or 90 days, choose a custom date, or create tokens that never expire. This endpoint allows external API and CLI users to authenticate directly with their FalkorDB credentials.
curl -X POST https://your-server.com/api/auth/tokens/credentials \
-H "Content-Type: application/json" \
-d '{
"username": "default",
"password": "",
"host": "localhost",
"port": "6379",
"tls": "false",
"name": "CI/CD Pipeline Token",
"ttlSeconds": 2592000
}'
This will output the following:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"tokenId": "1761055513181-215c579b",
"expiresAt": "2025-12-24T12:00:00Z"
}
## Note: For browser users with an active session, use POST /api/auth/tokens which does not require credentials in the request body.
2: List tokens
GET /api/auth/tokens
View all your active tokens with metadata including creation date, last used timestamp, and expiration. Admins see all tokens, while regular users see only their own.
curl -X GET https://your-server.com/api/auth/tokens \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
This will output the following:
{
"tokens": [
{
"token_id": "1761055513181-215c579b",
"user_id": "user-abc123",
"username": "default",
"name": "CI/CD Pipeline Token",
"role": "Admin",
"host": "localhost",
"port": 6379,
"created_at": "2025-11-24T12:00:00Z",
"expires_at": "2025-12-24T12:00:00Z",
"last_used": "2025-11-24T14:30:00Z"
}
],
"count": 1,
"role": "Admin"
}
3: Get token by ID
GET /api/auth/tokens/{tokenId}
Retrieve detailed information about a specific token. Only the token owner or admins access this endpoint.
curl -X GET https://your-server.com/api/auth/tokens/1761055513181-215c579b \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
This will output the following:
{
"token": {
"token_id": "1761055513181-215c579b",
"user_id": "user-abc123",
"username": "default",
"name": "CI/CD Pipeline Token",
"role": "Admin",
"host": "localhost",
"port": 6379,
"created_at": "2025-11-24T12:00:00Z",
"expires_at": "2025-12-24T12:00:00Z",
"last_used": "2025-11-24T14:30:00Z",
"is_active": true
}
}
4: Revoke token
DELETE /api/auth/tokens/{tokenId}
Immediately revoke a token when you no longer need it or if you suspect security compromise. Only the token owner or admins revoke tokens.
curl -X DELETE https://your-server.com/api/auth/tokens/1761055513181-215c579b \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
This will return:
{
"message": "Token revoked successfully",
"tokenId": "1761055513181-215c579b"
}
Token Management Methods
Method 1: Browser UI (GUI Access)
Navigate to the Settings page in FalkorDB Browser to access the token management interface. You create tokens with a few clicks, copy them securely (we show them only once), and view or revoke existing tokens without writing code.
Use Case: Users who prefer a visual interface, one-off token generation, and quick token management.
Method 2: External API Access (Developer Access)
Use the documented Swagger UI at /docs to explore and test all endpoints interactively. The OpenAPI specification provides:
- Complete request/response schemas
- Interactive “Try it out” functionality
- Code generation for multiple languages
- Authentication examples
Alternatively, use curl commands or your preferred HTTP client to integrate token management directly into your workflows.
Use Case: Automated scripts, CI/CD pipelines, infrastructure as code, and programmatic token rotation.
Authentication flows
FalkorDB Browser supports two authentication methods for different use cases:
Session-Based Authentication (Browser Users)
- Log in through the web interface using NextAuth
- Generate tokens via the UI or POST /api/auth/tokens (no credentials needed)
- Use tokens for API requests
Credential-Based Authentication (API/CLI Users)
- Generate tokens directly with POST /api/auth/tokens/credentials (includes credentials)
- Receive a JWT token immediately
- Use the token for all subsequent API calls
Both methods support the same token management operations (list, retrieve, revoke) and provide identical security guarantees.
Security implementation
Our implementation follows industry best practices:
- JWT-based authentication: Stateless, scalable API access using HS256 algorithm
- AES-256-GCM encryption: We encrypt password storage; the token never stores your password
- Role-based access control: Users manage only their own tokens (unless they hold admin status)
- Immediate revocation: Revocation takes effect instantly across all requests
- Token expiration: Supports both TTL (seconds) and absolute date
- Usage tracking: Tracks last_used timestamps (throttled to 5-minute intervals for performance)
- Secure token storage: Uses SHA-256 hashes in FalkorDB
Getting started
Option 1: Using the Browser UI
- Log into FalkorDB Browser and navigate to Settings > Personal Access Tokens
- Click “Generate Token” and assign a meaningful name
- Copy your token: We display it only once for security
- Start making API requests using Authorization: Bearer YOUR_TOKEN
Option 2: Using the API Directly
- Generate a token with your FalkorDB credentials:
curl -X POST https://your-server.com/api/auth/tokens/credentials \
-H "Content-Type: application/json" \
-d '{
"username": "default",
"password": "",
"host": "localhost",
"port": "6379",
"name": "My API Token",
"ttlSeconds": 2592000
}'
2. Save the returned token securely
3. Use the token in all subsequent API requests with the Authorization: Bearer YOUR_TOKEN header
You can also explore the API directly at /docs using the interactive Swagger documentation.
Personal Access Tokens improve how you interact with FalkorDB:
- Automation: Build scripts and integrations without hard-coding passwords
- Security: Revoke compromised tokens instantly without changing your main password
- Flexibility: Create multiple tokens for different applications with individual expiration dates
- Transparency: Track when and where each token sees use
- Dual Access: Use the browser UI for convenience or the API for automation
Whether you develop integrations or automate graph operations, Personal Access Tokens provide the secure, flexible authentication you require.
Generate your first token today to test FalkorDB authentication updates.
FAQ
How do I generate a FalkorDB Personal Access Token?
POST to /api/auth/tokens/credentials with your credentials, or use the Browser UI Settings. You can define custom expiration times or set tokens to never expire.
What encryption standards enforce token security?
We use HS256 for stateless JWT authentication and AES-256-GCM to encrypt stored credentials. We hash token identifiers with SHA-256 for secure lookups.
Can I revoke a token immediately if compromised?
Yes. Send a DELETE request to /api/auth/tokens/{tokenId} using the API or click “Revoke” in the Browser UI. Revocation propagates instantly across all requests.
