Skip to main content

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

  1. 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
  2. User authentication: If not already logged in, the user is redirected to login first (standard Unraid auth)

  3. 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
  4. 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
  5. Callback: App receives the API key:

    https://myapp.com/callback?api_key=xxx&state=abc123

Query Parameters

  • name (required): Name of the requesting application
  • description (optional): Description of the application
  • scopes (required): Comma-separated list of requested scopes
  • redirect_uri (optional): URL to redirect after authorization
  • state (optional): Opaque value for maintaining state

Scope Format

Scopes follow the pattern: resource:action

Examples:

  • docker:read - Read access to Docker
  • vm:* - Full access to VMs
  • system:update - Update access to system
  • role:viewer - Viewer role access
  • role: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

  1. HTTPS required: Redirect URIs must use HTTPS (except localhost for development)
  2. User consent: Users explicitly approve each permission
  3. Session-based: Uses existing Unraid authentication session
  4. 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);
}