Skip to main content

​
Overview

Homarr supports two primary authentication methods:
  1. Session Authentication - Cookie-based authentication for web clients
  2. API Key Authentication - Token-based authentication for external applications

​
Session Authentication

Session authentication is used by the Homarr web interface and is based on NextAuth.js.

​
How It Works

  1. User logs in via the web interface
  2. Server creates a session and stores a session token in an HTTP-only cookie
  3. Subsequent requests include the session cookie automatically
  4. Server validates the session token on each request
​
next-auth.session-token
string
Session token cookie name. HTTP-only, secure, SameSite=Lax.

​
Using Session Authentication

For web applications, session authentication is handled automatically: 
// tRPC client uses session cookie automatically
const { data } = api.user.getById.useQuery({ userId: "user-id" });

​
API Key Authentication

API keys allow external applications to authenticate without maintaining a session.

​
Creating an API Key

Only administrators can create API keys.
1

Navigate to Settings

Go to Settings → API Keys in the Homarr interface
2

Generate New Key

Click “Create API Key” to generate a new key
3

Save the Key

The full API key is displayed only once. Save it securely.

​
API Key Format

API keys have the format: {id}.{token} Example: clx1234567890.a1b2c3d4e5f6...
  • ID: Identifies the API key in the database
  • Token: Secret token used for authentication (64 characters)

​
Using API Keys

​
HTTP Headers

Include the API key in the Authorization header: 
curl -X GET https://your-homarr.com/api/trpc/board.getAllBoards \
  -H "Authorization: Bearer clx1234567890.a1b2c3d4e5f6..."

​
tRPC Client

For programmatic access with tRPC: 
import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from '@homarr/api';
import superjson from 'superjson';

const client = createTRPCProxyClient<AppRouter>({
  transformer: superjson,
  links: [
    httpBatchLink({
      url: 'https://your-homarr.com/api/trpc',
      headers: {
        Authorization: 'Bearer clx1234567890.a1b2c3d4e5f6...',
      },
    }),
  ],
});

// Use the client
const boards = await client.board.getAllBoards.query();

​
API Key Security

API keys have the same permissions as the user who created them. Treat them like passwords.
Best Practices:
  • Store API keys in environment variables, not in code
  • Use separate API keys for different applications
  • Rotate API keys periodically
  • Delete unused API keys immediately
  • Never commit API keys to version control

​
Managing API Keys

​
List All API Keys

const keys = await api.apiKeys.getAll.query();
// Returns: Array of API key metadata (without the secret token)
​
id
string
Unique identifier for the API key
​
userId
string
ID of the user who owns this API key
​
user
object
User information
​
id
string
User ID
​
name
string
User name
​
email
string
User email
​
image
string | null
User profile image URL

​
Create API Key

const result = await api.apiKeys.create.mutate();
console.log(result.apiKey); // "clx1234567890.a1b2c3d4e5f6..."
The full API key (including the token) is only returned once during creation. Store it securely.

​
Delete API Key

await api.apiKeys.delete.mutate({ apiKeyId: "clx1234567890" });

​
WebSocket Authentication

WebSocket connections authenticate using the session cookie: 
import { createWSClient } from '@trpc/client';

const wsClient = createWSClient({
  url: 'ws://localhost:3001',
  // Cookie is sent automatically from browser
});
For programmatic WebSocket connections, include the session token in the cookie header: 
const ws = new WebSocket('ws://localhost:3001', {
  headers: {
    Cookie: `next-auth.session-token=${sessionToken}`,
  },
});

​
Permissions

Authenticated requests inherit the permissions of the user or API key owner:
  • Public procedures: No authentication required
  • Protected procedures: Require valid session or API key
  • Permission-required procedures: Require specific permissions (e.g., admin, board-create)

​
Common Permissions

PermissionDescription
adminFull administrative access
board-createCreate new boards
board-view-allView all boards
board-modify-allModify all boards
app-createCreate applications
integration-createCreate integrations
integration-use-allUse all integrations
See the User Management guide for more details about permissions.

​
Troubleshooting

​
”Unauthorized” Error

  • Verify your API key is correct
  • Check that the API key hasn’t been deleted
  • Ensure the Authorization header is properly formatted

​
”Forbidden” Error

  • Verify the user has the required permissions
  • Check that the resource is accessible to the user

​
Session Expires

Sessions expire after a period of inactivity. Users must log in again to create a new session.

Build docs developers (and LLMs) love

Get started for freeTalk to us