Authentication

Unscrambled supports two types of authentication: OAuth flows for services that use them, and API key storage for services that issue static keys. In both cases, credentials are encrypted and stored in Unscrambled's vault — they never exist in plaintext on your machine.

OAuth services

For OAuth-based services, Unscrambled manages the full flow: authorization URL, PKCE challenge, callback server, token exchange, and token refresh.

unscrambled auth add hubspot

When you run this command:

1. Unscrambled starts a temporary local callback server
2. Your browser opens to the service's authorization page
3. You approve the requested permissions
4. The authorization code is exchanged for access and refresh tokens
5. Tokens are encrypted and stored in the Unscrambled vault
6. The local callback server shuts down

Token refresh happens automatically. When a token expires, Unscrambled uses the stored refresh token to obtain a new access token before your API call is made. You never see an auth error.

Supported OAuth services

Custom OAuth scopes

You can request specific scopes when adding a service:

unscrambled auth add github --scope repo,read:user,admin:org

API key services

For services that use static API keys, Unscrambled prompts you once, encrypts the key, and stores it. The key is never written to disk on your machine.

unscrambled auth add openai

OpenAI uses API keys. Paste your key:
sk-proj-████████████████████████
✓ API key encrypted and stored.

Supported API key services

Custom services

You can add any REST API by providing the auth configuration manually:

unscrambled auth add my-api \
  --type api-key \
  --header "X-Api-Key" \
  --base-url "https://api.example.com"

For custom OAuth services:

unscrambled auth add my-oauth-service \
  --type oauth2 \
  --auth-url "https://example.com/oauth/authorize" \
  --token-url "https://example.com/oauth/token" \
  --client-id "your-client-id" \
  --scope "read,write"

Managing credentials

List connected services

unscrambled auth list

SERVICE      TYPE       STATUS       CONNECTED
github       OAuth      ✓ Active     2 days ago
openai       API Key    ✓ Active     1 hour ago
hubspot      OAuth      ⚠ Expired    5 days ago (re-auth required)

Remove a service

unscrambled auth remove github

This revokes the token (where the service supports it) and deletes the encrypted credential from the vault.

Re-authenticate

If an OAuth token can't be refreshed (e.g., the refresh token was revoked), re-run the auth command:

unscrambled auth add github

It will replace the existing credential.

How credentials are secured

Unscrambled uses three-tier envelope encryption:

1. Master key — Managed by AWS KMS, never leaves the HSM
2. Account encryption key — Unique to your account, wrapped by the master key
3. Data encryption key — Unique per credential, wrapped by your account key

The actual credential (OAuth token or API key) is encrypted with AES-256-GCM using the data encryption key. Decryption only happens in memory on the server, for the duration of an API call. Credentials are never logged, cached to disk, or included in error responses.

What is not stored on your machine

• OAuth access tokens
• OAuth refresh tokens
• API keys
• Client secrets

What is stored on your machine

• Your Unscrambled session token (in ~/.unscrambled/session.json)
• A list of connected services (names only, no credentials)