# Using Hub API keys in OAK Apps and scripts

Use this page when you need to pass a Luxonis Hub API key into local scripts or devices that are not adopted to Luxonis Hub,
without exposing the key in source control.

For creating and managing API keys themselves, use [API keys in Luxonis Hub](https://docs.luxonis.com/cloud/api/api-keys.md). This
page focuses on how to use those keys safely with Luxonis software.

Adopted devices and OAK Apps managed through Luxonis Hub do not need team API keys. Hub handles authentication for them with
device-level permissions that are more appropriate than a shared team API key.

> **Hub API keys have full team admin access**
> Treat Hub API keys as high-sensitivity secrets. They currently have full admin access to your team's resources.
> [See more](https://docs.luxonis.com/cloud/api/api-keys.md)
> .

Manual API key handling is mainly relevant for:

 * devices not adopted to Luxonis Hub that need to download private models from Models Registry
 * local scripts

Do not place API keys directly in git-tracked files such as oakapp.toml, Python source files, JSON, YAML, or shell scripts.
Instead, use runtime-only injection patterns such as environment variables, .env files, or oakctl login flows.

## General Recommendations

 * Never commit API keys directly into repositories (e.g., .toml, .json, .yaml, or .py files under git).
 * Prefer using environment variables or .env files (excluded from git via .gitignore).
 * Do not add team API keys to adopted-device or Hub-managed OAK App workflows unless you have a specific non-Hub requirement.
 * Prefer oakctl-managed authentication or local runtime injection when you do need a key.
 * Keep .env files local only, and avoid sharing them.

## Modes & Secure Setup Options

#### Standalone Mode

## When you do not need to pass a key manually

If the device is adopted to Luxonis Hub, or the app is deployed and managed through Hub, you usually do not need to manage a team
API key manually. Hub handles authentication through the adopted-device flow with device-level permissions.

## Local and device-side setup

### Option 1 - Device adopted

If the device is already adopted by your team in Hub, you should not need to provide a team API key manually. Run the app with:

```bash
oakctl app run .
```

### Option 2 - Override the Key

If the device is not adopted to Hub, override DEPTHAI_HUB_API_KEY.

In that case, load the value from a local .env file:

```python
import os
from dotenv import load_dotenv

load_dotenv(override=True)

print(os.environ["DEPTHAI_HUB_API_KEY"])
```

Then store the key in a .env file next to main.py:

```bash
cd <INSERT_PATH_TO_PROJECT>
echo "DEPTHAI_HUB_API_KEY=<INSERT_YOUR_DEPTHAI_HUB_API_KEY>" > .env
echo ".env" >> .gitignore
```

Then run:

```bash
oakctl app run .
```

oakctl copies the .env file into the app environment on the device. Your app still needs its own logic to read that value at
runtime, for example with dotenv.load_dotenv().

#### Peripheral Mode

## oakctl-managed authentication

If oakctl is driving a workflow for a device that is not adopted to Hub, use its Hub login flow instead of hardcoding raw keys
manually:

```bash
oakctl hub login
oakctl run-script python3 main.py
```

After logging in, oakctl provides the Hub authentication context to the script. You can log out later with oakctl hub logout.

## Local script setup

If you are running the script directly, use one of the following patterns:

### Option 1 - Inline parameter

Read the value from a CLI argument:

```python
_, args = initialize_argparser()

if args.api_key:
    print(args.api_key)
```

Call from the command line:

```bash
python3 <INSERT_PATH_TO_PROJECT>/main.py -api <INSERT_YOUR_DEPTHAI_HUB_API_KEY>
```

### Option 2 - .env file

Load the key from a local .env file:

```python
import os
from dotenv import load_dotenv

load_dotenv(override=True)
print(os.environ["DEPTHAI_HUB_API_KEY"])
```

and then execute the following commands:

```bash
cd <INSERT_PATH_TO_PROJECT>
echo "DEPTHAI_HUB_API_KEY=<INSERT_YOUR_DEPTHAI_HUB_API_KEY>" > .env
echo ".env" >> .gitignore
python3 <INSERT_PATH_TO_PROJECT>/main.py
```

### Option 3 - Exported environment variable

Read the key from the process environment:

```python
import os
print(os.environ["DEPTHAI_HUB_API_KEY"])
```

Then execute:

```bash
cd <INSERT_PATH_TO_PROJECT>
export DEPTHAI_HUB_API_KEY=your_key_here
python3 main.py
```

## Example

See the [generic neural net example from
oak-examples](https://github.com/luxonis/oak-examples/blob/dynamic_calib/neural-networks/generic-example/main.py) for one
practical pattern.