dune-key

OAuth token fetcher for Cognite Data Fusion. Opens your browser, authenticates, and outputs the access token to stdout.

Usage

Get a token

# Use with npx (no installation needed)
npx dune-key

# Force new authentication (bypass cache)
npx dune-key --force

The command opens your browser for authentication and outputs the token to stdout.

Token caching: Tokens are automatically cached for 4 hours in ~/.dune-key-cache/. Subsequent calls within 4 hours will use the cached token instead of re-authenticating. Use --force to bypass the cache and get a fresh token.

Use in shell scripts

# Export to environment variable
export CDF_TOKEN="$(npx dune-key)"

# Use inline with other environment variables
CDF_PROJECT="myproject" CDF_TOKEN="$(npx dune-key)" npm run dev

# Set multiple variables
CDF_PROJECT="lervik-industries" CDF_TOKEN=$(npx dune-key)

# Use in scripts
TOKEN=$(npx dune-key)
curl -H "Authorization: Bearer $TOKEN" \
  https://api.cognitedata.com/api/v1/projects/myproject/assets

How It Works

1. Starts local HTTPS server on port 3000
2. Opens browser to Cognite's OAuth login
3. You authenticate with your credentials
4. Token is printed to stdout (errors go to stderr)

Configuration (Optional)

All settings have sensible defaults. Create a .env file if you need custom configuration:

CDF_CLIENT_ID=c6f97d29-79a5-48ac-85de-1de8229226cb  # Default CDF public client
CDF_AUTHORITY=https://auth.cognite.com
CDF_REDIRECT_URI=https://localhost:3000
CDF_SCOPES=openid,profile,email
CDF_ORG=your-organization  # For multi-tenant setups

First Run

On first run, your browser may warn about a self-signed certificate. This is expected for localhost OAuth - accept it to continue. Certificates are stored in ~/.dune-key-certs/.

Troubleshooting

Browser doesn't open? The auth URL will be printed - copy/paste it manually.

Certificate errors? Regenerate with: rm -rf ~/.dune-key-certs/

Port 3000 in use? Set CDF_REDIRECT_URI to a different port in .env

Clear cached token: rm -rf ~/.dune-key-cache/ or use --force flag

Exit Codes

• 0 - Success
• 1 - General error
• 2 - Authentication timeout
• 3 - Security validation failed
• 4 - OAuth provider error
• 5 - Server error (port in use)

Installation (Optional)

If you prefer to install globally instead of using npx:

npm install -g dune-key
dune-key

Development

To build from source:

git clone https://github.com/cognitedata/dune-key.git
cd dune-key
npm install
npm run build
./dune-key

Documentation

• Quick Start Guide
• Architecture Details
• Changelog

License

MIT