> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Inject secrets into services

You can inject secret information into your service as an environment variable during execution. Examples of secret information you may want to inject include passwords, API tokens, and AWS credentials.

The secret name used in the syntax below can refer to either a secret stored in Gateway's local secret store or an [external secret alias](./secrets/external-secrets/manage-secret-aliases). The injection syntax is the same in both cases.

Although using environment variables to set secret information is common practice, consider the security risks that can occur when environment variables contain secret information.

## Prerequisites

* Gateway 5.2 or later
* Gateway secret store configured with an encryption key

If you haven't created your Gateway secret store yet, see [Configure Gateway secret store](./configure-secret-store).

## Associate secrets on service creation

You can associate secrets stored in Gateway's secret store with a service when you create it using the `--secret` flag within any of the `iagctl create service` commands.

The `--secret` flag uses the following syntax:

```bash
--secret name=name-of-secret-in-secret-store,type=env,target=ENV_VAR_NAME
```

The syntax has three sections separated by commas:

* **name** - The name of the secret in the secret store
* **type** - How the secret will be injected into the service (must be set to `env`, as only environment variables are supported)
* **target** - The name of the environment variable that will be set during execution

The following example creates a Python Script service called `my-script`. The service uses an API key stored in Gateway's secret store called `my-api-key`. The value of `my-api-key` will be injected into the script at execution time using an environment variable called `API_KEY`:

```bash
iagctl create service python-script my-script \
--secret name=my-api-key,type=env,target=API_KEY \
--repository my-repo \
--filename main.py
```

This ensures that the API key is injected into the service during every execution.

## Associate secrets on service execution

To specify that a secret should be injected into a service when running a service via the CLI, you can use the `--set-secret` flag available on the `iagctl run service` commands or specify that a secret is being used on a decorator.

### Use the --set-secret flag

The `--set-secret flag` uses the same syntax as the flag used at service creation time.

The following example specifies that a secret stored in Gateway's secret store called `my-password` should be injected as an environment variable called `PASSWORD`:

```bash
iagctl run service python-script some-script \
--set-secret name=my-password,type=env,target=PASSWORD
```

### Specify secrets on decorators

You can specify that a secret should be injected into a service at runtime using the custom annotations `x-itential-secret-type` and `x-itential-secret-target`. A decorator that requests the name of a secret in the secret store with a value of a password would look like this:

```json
{
  "$id": "root",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "password": {
      "type": "string",
      "x-itential-secret-type": "env",
      "x-itential-secret-target": "PASSWORD"
    }
  },
  "required": [
    "password"
  ],
  "additionalProperties": false
}
```

The value given for password will be the name of the secret in Gateway's secret store. `x-itential-secret-type` must be set to `env`, as it denotes that the password will be injected into the service as an environment variable when executed. Environment variables are currently the only secret type available. `x-itential-secret-target` denotes the name of the environment variable to be injected when the service is executed.

Since the name of a secret in Gateway's secret store is always a string, secret properties for decorators must always be of type string.

After you have a secret set on a decorator, you can specify the name of the secret in the secret store using the `--set` flag as you normally would for decorator values.

If you have a Python script that uses the decorator above, and you have a password in the secret store called `my-password`, you would use this syntax:

```bash
iagctl run service python-script my-script --set password=my-password
```

The system injects the value of the secret `my-password` into the Python script as an environment variable with a key of `PASSWORD`. Services that have decorators with injected secret values can then be executed through the **runService** Gateway Manager task.