Using secure App secrets

App secrets provide a secure storage and access method for all the credentials your App needs to run.


Your App needs confidential access details to connect to other services (user-names, passwords, API keys or alike). Those can be on fortrabbit like the MySQL database access, or externally like an API key for a queue or something. You are as paranoid as we are, regarding storing those details in ENV vars.


Use fortrabbit App secrets to store your credentials safely. App secrets are stored in a JSON file called secrets.json which is only accessible by you and your App. The location of this JSON file is stored in a predefined environment variable called APP_SECRETS.

App secrets vs ENV vars

App secrets are closely related to ENV vars insofar that they are both available to your App at runtime. The big difference between them is that App secrets are stored highly secured and they are not automatically dumped out by debug tools - such as phpinfo() or your favorite debug toolbar.

Since App secrets are a rather unique concept, they are completely optional to use. Per default, new Apps make all App secrets available as dynamic ENV vars. If you prefer to use only App secrets, then you can disable this behavior.

App secrets in your App

Access App secrets from inside your App via PHP like so:

// read all App secrets from the JSON file, get the location via ENV var
$secrets = json_decode(file_get_contents($_SERVER["APP_SECRETS"]), true);

// use a specific secret
$meaning_of_life = $secrets['CUSTOM']['MEANING_OF_LIFE'];
// App secrets are ordered in a tree structure:
$secrets == [
    'MYSQL' => [
        'PASSWORD' => "{{mysql-password}}",
        'USER'     => "{{mysql-user}}",
        'DATABASE' => "{{mysql-database}}",
        'HOST'     => "{{mysql-host}}",
        'PORT'     => "{{mysql-port}}",
    'CUSTOM' => [
        'yourOtherCustomSecret' => "{{yourOtherCustomSecret}}"

See an example to use the App secrets to connect to MySQL for Laravel.

App secrets from local

Read App secrets from your local machine by using an SSH remote exec command in your terminal:

# show all App secrets
$ ssh {{ssh-user}}@deploy.{{region}} secrets
# {
#     "MYSQL": {
#         "PASSWORD": "{{mysql-password}}",
#         "USER": "{{app-name}}",
#         "DATABASE": "{{app-name}}",
#         "HOST": "{{app-name}}.mysql.{{region}}",
#         "PORT": "3306",
#     },
#     "CUSTOM": {
#         "YOUR_CUSTOM_SECRET": "The custom content",
#         "yourOtherCustomSecret": "The custom content"
#     }
# }

# show only MySQL secrets
$ ssh {{ssh-user}}@deploy.{{region}} secrets MYSQL
# {
#     "PASSWORD": "{{mysql-password}}",
#     "USER": "{{app-name}}",
#     "DATABASE": "{{app-name}}",
#     "HOST": "{{app-name}}.mysql.{{region}}",
#     "PORT": "3306",
# }

# show only MySQL password
$ ssh {{ssh-user}}@deploy.{{region}} secrets MYSQL.PASSWORD
# {{mysql-password}}

Adding custom App secrets

You can add or remove custom App secrets in the Dashboard. You'll do so in the settings of your App. The contents of the App secrets cannot be viewed in the Dashboard due to the underlying encryption, which we consider a feature, not a bug.

You can overwrite old values by adding new values to the same keys or by first deleting the App Secrets with the "delete" button.

See App secrets of your App {{app-name}} Add new App secrets for your App {{app-name}}

App secrets vs local environment

Since access to your App secrets should be done using $_SERVER['APP_SECRETS'], you can easily set this environment variable locally with a path to a local JSON file containing your local (dummy) secrets.

All articles

Craft CMS


Install guides

Code access














The Dashboard


Tips & tricks




Need individual help?
Learn about Company plans ›
Looking for an old article?
See the full list of articles ›
Found an error?
Contribute on GitHub ›