OverviewHardwareSoftwareCloud
OAK Apps
DepthAI
AI
Software Stack
Troubleshooting

ON THIS PAGE

  • General Recommendations
  • Modes & Secure Setup Options

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. 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.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:
Command Line
1oakctl 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
1import os
2from dotenv import load_dotenv
3
4load_dotenv(override=True)
5
6print(os.environ["DEPTHAI_HUB_API_KEY"])
Then store the key in a .env file next to main.py:
Command Line
1cd <INSERT_PATH_TO_PROJECT>
2echo "DEPTHAI_HUB_API_KEY=<INSERT_YOUR_DEPTHAI_HUB_API_KEY>" > .env
3echo ".env" >> .gitignore
Then run:
Command Line
1oakctl 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:
Command Line
1oakctl hub login
2oakctl 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
1_, args = initialize_argparser()
2
3if args.api_key:
4    print(args.api_key)
Call from the command line:
Command Line
1python3 <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
1import os
2from dotenv import load_dotenv
3
4load_dotenv(override=True)
5print(os.environ["DEPTHAI_HUB_API_KEY"])
and then execute the following commands:
Command Line
1cd <INSERT_PATH_TO_PROJECT>
2echo "DEPTHAI_HUB_API_KEY=<INSERT_YOUR_DEPTHAI_HUB_API_KEY>" > .env
3echo ".env" >> .gitignore
4python3 <INSERT_PATH_TO_PROJECT>/main.py

Option 3 - Exported environment variable

Read the key from the process environment:
Python
1import os
2print(os.environ["DEPTHAI_HUB_API_KEY"])
Then execute:
Command Line
1cd <INSERT_PATH_TO_PROJECT>
2export DEPTHAI_HUB_API_KEY=your_key_here
3python3 main.py

Example

See the generic neural net example from oak-examples for one practical pattern.