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 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. 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 ### 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 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 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 cryptographic operations and security measures (session management, CSRF protection, etc..). Therefore this
value should be handled as confidential data and not shared publicly. 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 * `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 part image gallery

View file

@ -75,6 +75,11 @@ services:
# Use gravatars for user avatars, when user has no own avatar defined # Use gravatars for user avatars, when user has no own avatar defined
- USE_GRAVATAR=0 - 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. # 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 # 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 #- 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 # 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 # 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. # 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 # When this is outcommented the webUI can be used to configure the banner
#- BANNER=This is a test banner<br>with a line break #- BANNER=This is a test banner<br>with a line break