---
question: Where do I put an integration API key?
kind: task
via_web: available
via_cli: na
via_python: available
via_api: available
via_config: available
ref_web: System › Data › Secrets
ref_python: secret.get
ref_api: PUT /api/admin/system/resources/secret/entry
ref_config: .env
prereq: You need a module whose `ModuleDependencies(services=(...))` lists `"secret"` (see [Read it from the module](#read-it-from-the-module) below).
next:
  - /capabilities/build/integrations/use-in-an-agent
  - /capabilities/build/integrations/test-an-integration
  - /capabilities/build/secrets/add-a-secret
---

# Add credentials

An integration gets its API key from the module that builds it. Adding a credential takes two things:

1. **Store the value** in the engine secret service. Its default adapter is `dotenv`, which reads and writes `.env` at the project root. Each tab below stores it a different way.
2. **Read it from the module** with `await self.engine.services.secret.get("MY_API_KEY")`, and pass it to the integration's configuration. That part is the same for every tab: see [Read it from the module](#read-it-from-the-module).

The module asks the engine for the value each time it calls `get`, so a value written through the secret service is seen without restarting the module. Never read the key from the module's own environment: it is not the engine's.

:::warning Two stores use the word secret
Workspace Settings › Secrets in Nexus (`POST /api/secrets`) stores rows in the workspace database. Modules cannot read those rows. Use the engine secret service, as on this page. See [Add a secret](/capabilities/build/secrets/add-a-secret).
:::

## Web UI

### Open the engine secrets

Open the **System** app from the sidebar, then the **Data** tab, then **Secrets**: "Credentials the engine reads from its secret adapters (.env, Naas)." The System app is for platform super admins only.

### Add the secret

Click **New secret**. Enter the name (`MY_API_KEY`: letters, digits, `_`, `.` and `-`, not starting with a digit) and the value, then save. It is written to every configured secret adapter, `.env` included.

![System app, Data tab, on Secrets: the New secret dialog](/abi/Screenshot_System_New_Secret.png)

*System › Data › Secrets › New secret. The value is saved as text and masked in the list.*

## CLI

Not applicable. There is no `abi` command that writes a single secret. `abi secrets naas push-env-as-base64` pushes a whole env file to a Naas secret, for the `naas` adapter. Use the Web UI, Python, the REST API, or put the value in `.env` (Config tab).

## Python

### Store the value

From a method of a module that declares the `secret` service, such as a job you run once:

```python
await self.engine.services.secret.set("MY_API_KEY", "sk-...")
```

`set` writes every configured adapter. A module that does not declare `secret` is refused the call.

### Check it

```python
secrets = await self.engine.services.secret.list()
assert "MY_API_KEY" in secrets
```

`list()` returns a dict of every secret, each name with its plaintext value (`None` when an adapter has no value for it). Check names only: never log or print the dict. `remove("MY_API_KEY")` deletes one.

## REST API

### Write the secret

```bash
curl -s -X PUT "http://localhost:9879/api/admin/system/resources/secret/entry?id=MY_API_KEY" \
  -H "Authorization: Bearer $NEXUS_ACCESS_TOKEN" \
  --data-binary 'sk-...'
```

This is the call behind the System app's Secrets view. The body is the raw value. The caller must be a platform super admin, signed in to Nexus (see [Enable in a workspace](/capabilities/build/knowledge-graph/enable-ontology?via=api) for the sign-in call). Replacing an existing secret also needs `&confirm=MY_API_KEY`.

## Config

### Put the value in .env

```bash title=".env"
MY_API_KEY=sk-...
```

The `dotenv` adapter reads `.env` at the project root, once, when the engine starts: restart the engine after an edit. The file must exist. A project without a `services.secret` block gets that adapter by default.

### Check the adapter block

```yaml title="config.yaml"
services:
  secret:
    secret_adapters:
      - adapter: "dotenv"
        config: {}
```

`config.path` names another file. Other adapters are `naas` and `base64`. The full block is in the [Configuration Reference](/user-guide/get-started/configuration#secret).

:::note The engine's environment and .env can disagree
The `dotenv` adapter's `get` takes the `.env` value first, and the engine's environment variable only when `.env` has no such key. Set `environment_first: true` on the adapter so a variable the deployment sets wins.
:::

## Read it from the module

Declare the service on the module:

```python title="src/my_module/__init__.py"
class ABIModule(BaseModule[MyModuleConfiguration]):
    dependencies = ModuleDependencies(
        services=("model_registry", "document", "triple_store", "secret")
    )
```

Read the key where the integration is built, for example in a workflow's `New(module)`:

```python title="src/my_module/workflows/ItemsWorkflow.py"
class ItemsWorkflow(Workflow[ItemsWorkflowParameters]):
    """List the items of the external service."""

    def __init__(self, configuration: ItemsWorkflowConfiguration, integration: MyIntegration):
        super().__init__(configuration)
        self.integration = integration

    @classmethod
    async def New(cls, module) -> "ItemsWorkflow":
        api_key = await module.engine.services.secret.get("MY_API_KEY", default="")
        integration = MyIntegration(MyIntegrationConfiguration(api_key=api_key))
        return cls(ItemsWorkflowConfiguration(), integration)
```

The base `Workflow.__init__` takes only the configuration, so a class built with more arguments defines its own `__init__` and calls `super().__init__(configuration)`.

`get(key, default=None)` returns the value, or `default` when no adapter has it. An agent built in `on_initialized` reads it the same way: see [Use in an agent](/capabilities/build/integrations/use-in-an-agent).
