Add INITIAL_ADMIN_API_KEY documentation

- Document environment variable in configuration.md
- Add section to API authentication documentation
- Include examples in Docker installation guide for both SQLite and MySQL setups
- Provide usage instructions for CI/CD and automated deployments
This commit is contained in:
Ryan Malloy 2025-09-07 08:42:17 -06:00
parent c498803859
commit 99cd18096b
3 changed files with 23 additions and 0 deletions

View file

@ -32,6 +32,14 @@ tokens as you want and also delete them again.
When deleting a token, it is immediately invalidated and can not be used anymore, which means that the application can
not access the API anymore with this token.
### Initial Admin API Token
For automated deployments and CI/CD pipelines, Part-DB supports automatically creating an initial admin API token
during database setup. Set the `INITIAL_ADMIN_API_KEY` environment variable to a 64-character random string
(generate with `openssl rand -hex 32`) before running database migrations. Part-DB will create an API token named
"Initial Admin Token" with FULL scope that expires after 1 year. The token can be used immediately with the format
`Bearer tcp_<your-64-char-key>` in the Authorization header.
### Token permissions and scopes
API tokens are ultimately limited by the permissions of the user, which belongs to the token. That means that the token

View file

@ -114,6 +114,11 @@ bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept
particularly for securing and protecting various aspects of your application. It's a secret key that is used for
cryptographic operations and security measures (session management, CSRF protection, etc..). Therefore this
value should be handled as confidential data and not shared publicly.
* `INITIAL_ADMIN_API_KEY` (env only): When set to a 64-character random string (generate with `openssl rand -hex 32`),
Part-DB will automatically create an API token named "Initial Admin Token" for the admin user during database
migrations. This token will have FULL scope and expire after 1 year. This is useful for automated deployments,
CI/CD pipelines, and Docker setups where you need immediate API access without manual token creation. The token
can be used with the format `Bearer tcp_<your-64-char-key>` in the Authorization header.
* `SHOW_PART_IMAGE_OVERLAY`: Set to 0 to disable the part image overlay, which appears if you hover over an image in the
part image gallery

View file

@ -75,6 +75,11 @@ services:
# Use gravatars for user avatars, when user has no own avatar defined
- USE_GRAVATAR=0
# Automatically create an admin API token during database setup (useful for CI/CD pipelines)
# Generate a 64-character random string with: openssl rand -hex 32
# The token will be available as: Bearer tcp_<your-64-char-key>
#- INITIAL_ADMIN_API_KEY=your_64_character_random_string_here
# Override value if you want to show a given text on homepage.
# When this is empty the content of config/banner.md is used as banner
#- BANNER=This is a test banner<br>with a line break
@ -146,6 +151,11 @@ services:
# However you can add add any other environment configuration you want here
# See .env file for all available options or https://docs.part-db.de/configuration.html
# Automatically create an admin API token during database setup (useful for CI/CD pipelines)
# Generate a 64-character random string with: openssl rand -hex 32
# The token will be available as: Bearer tcp_<your-64-char-key>
#- INITIAL_ADMIN_API_KEY=your_64_character_random_string_here
# Override value if you want to show to show a given text on homepage.
# When this is outcommented the webUI can be used to configure the banner
#- BANNER=This is a test banner<br>with a line break