API Key Authorization Flow
This document describes the self-service API key creation flow for third-party applications.
Overview
Applications can request API access to an Unraid server by redirecting users to a special authorization page where users can review requested permissions and create an API key with one click.
Flow
-
Application initiates request: The app redirects the user to:
https://[unraid-server]/ApiKeyAuthorize?name=MyApp&scopes=docker:read,vm:*&redirect_uri=https://myapp.com/callback&state=abc123
-
User authentication: If not already logged in, the user is redirected to login first (standard Unraid auth)
-
Consent screen: User sees:
- Application name and description
- Requested permissions (with checkboxes to approve/deny specific scopes)
- API key name field (pre-filled)
- Authorize & Cancel buttons
-
API key creation: Upon authorization:
- API key is created with approved scopes
- Key is displayed to the user
- If
redirect_uri
is provided, user is redirected back with the key
-
Callback: App receives the API key:
https://myapp.com/callback?api_key=xxx&state=abc123
Query Parameters
name
(required): Name of the requesting applicationdescription
(optional): Description of the applicationscopes
(required): Comma-separated list of requested scopesredirect_uri
(optional): URL to redirect after authorizationstate
(optional): Opaque value for maintaining state
Scope Format
Scopes follow the pattern: resource:action
Examples:
docker:read
- Read access to Dockervm:*
- Full access to VMssystem:update
- Update access to systemrole:viewer
- Viewer role accessrole:admin
- Admin role access
Available Resources:
docker
,vm
,system
,share
,user
,network
,disk
, etc.
Available Actions:
create
,read
,update
,delete
or*
for all
Security Considerations
- HTTPS required: Redirect URIs must use HTTPS (except localhost for development)
- User consent: Users explicitly approve each permission
- Session-based: Uses existing Unraid authentication session
- One-time display: API keys are shown once and must be saved securely
Example Integration
// JavaScript example
const unraidServer = 'tower.local';
const appName = 'My Docker Manager';
const scopes = 'docker:*,system:read';
const redirectUri = 'https://myapp.com/unraid/callback';
const state = generateRandomState();
// Store state for verification
sessionStorage.setItem('oauth_state', state);
// Redirect user to authorization page
window.location.href =
`https://${unraidServer}/ApiKeyAuthorize?` +
`name=${encodeURIComponent(appName)}&` +
`scopes=${encodeURIComponent(scopes)}&` +
`redirect_uri=${encodeURIComponent(redirectUri)}&` +
`state=${encodeURIComponent(state)}`;
// Handle callback
const urlParams = new URLSearchParams(window.location.search);
const apiKey = urlParams.get('api_key');
const returnedState = urlParams.get('state');
if (returnedState === sessionStorage.getItem('oauth_state')) {
// Save API key securely
saveApiKey(apiKey);
}