Skip to content

Authentication

Jump to bottom
Eric Mann edited this page Mar 19, 2026 · 3 revisions

Authentication and API Keys

Displace uses API key authentication to manage access to cloud providers, premium templates, and subscription features. This guide covers the authentication system and subscription tiers.

Overview

flowchart LR
    subgraph community["Community (no login)"]
        local["Local k3d clusters"]
        wp_free["All templates"]
    end

    subgraph paid["Authenticated (API Key)"]
        cloud["Cloud providers<br/>AWS, GCP, Azure, DO"]
        templates["All templates"]
        support["Priority support"]
    end

    user["User"] -->|"No login"| community
    user -->|"displace auth login"| paid
Loading

Key Points:

  • Local development is always free - no login required
  • Cloud providers require authentication and a paid subscription
  • API keys are obtained from your displace.tech dashboard

Authentication Commands

displace auth login

Authenticate with your Displace API key.

displace auth login

Expected output:

Welcome to Displace!

To get started, you'll need your API key from your Displace dashboard.
Visit https://displace.tech to create an account and get your API key.

Enter your API key: ****************************************************************

Validating API key...

✓ Successfully logged in as John Smith (john@example.com)
  Company: Acme Corp
  Subscription: Professional (active)
  Available providers: local, aws, gcp, digitalocean
  Available templates: wordpress, laravel, static, simplephp

You're all set! You can now use the Displace CLI.
Try running 'displace auth status' to see detailed subscription information,
or 'displace --help' to see all available commands.

displace auth status

View your current authentication status and subscription details.

displace auth status

Expected output (authenticated):

🔍 Displace Authentication Status
====================================

✅ Logged in (API Key: a1b2c3d4...)

📋 User Information:
   Name: John Smith
   Email: john@example.com
   Company: Acme Corp

💳 Subscription Details:
   Tier: Professional
   Status: Active
   Active: true
   Data Source: Stripe API (real-time)

🌐 Available Providers:
   ✅ local
   ✅ aws
   ✅ gcp
   ✅ digitalocean
   Unavailable providers:
   ❌ azure
   ❌ linode

📄 Available Templates:
   ✅ wordpress
   ✅ laravel
   ✅ static
   ✅ simplephp

🎫 Token Information (Cached):
   Issued: 2026-01-07 10:30:00 UTC
   Expires: 2026-01-07 22:30:00 UTC
   Valid for: 11h45m
   Version: 1

Expected output (not authenticated):

🔍 Displace Authentication Status
====================================

❌ Not logged in
   Run 'displace auth login' to authenticate

💳 Subscription Details:
   Tier: Community Plan (Free)
   Status: Active
   Active: true

🌐 Available Providers:
   ✅ local
   Unavailable providers:
   ❌ aws
   ❌ gcp
   ❌ azure

📄 Available Templates:
   ✅ wordpress

💡 Upgrade Information:
   💡 Ready to upgrade? Get access to the aws, gcp, and azure providers today.
   See https://displace.tech for more details.

Flags:

Flag Description
--refresh Refresh entitlements cache from server
--no-cache Bypass cache entirely and fetch fresh data 
# Force refresh subscription data
displace auth status --refresh

# Bypass cache completely
displace auth status --no-cache

displace auth logout

Remove stored credentials and cached entitlements.

displace auth logout

Expected output:

Successfully logged out.

Getting Your API Key

Step 1: Create an Account

  1. Visit displace.tech
  2. Click "Sign Up" or "Get Started"
  3. Complete the registration process

Step 2: Choose a Subscription

Select a plan that fits your needs (see Subscription Tiers below).

Step 3: Get Your API Key

  1. Log in to your Displace dashboard
  2. Navigate to Settings → API Keys
  3. Click Generate New Key
  4. Copy the 64-character API key

Security Note: Your API key is shown only once. Store it securely. If lost, generate a new one.

Step 4: Authenticate CLI

displace auth login
# Paste your API key when prompted

Subscription Tiers

flowchart TB
    subgraph tiers["Subscription Tiers"]
        community["Community<br/>(Free)"]
        starter["Starter<br/>($29/mo per cluster)"]
        professional["Professional<br/>($79/mo per cluster)"]
        founder["Founder<br/>($499/mo flat)"]
    end

    community -->|"Upgrade"| starter
    starter -->|"Upgrade"| professional
    professional -->|"Upgrade"| founder
Loading

Community Plan (Free)

No login required.

Feature Access
Local k3d clusters ✅ Unlimited
Cloud providers ❌ None
Templates All templates
Support Community

Best for: Learning Kubernetes, local development, testing.

# No login needed for local development
displace install
displace project init wordpress
displace project deploy --cluster displace-local

Starter Plan

Single cloud provider.

Feature Access
Local k3d clusters ✅ Unlimited
Cloud providers ✅ One provider (locked after first use)
Templates All templates
Support Email

Provider Lock: Once you deploy to a cloud provider (e.g., AWS), you're locked to that provider on the Starter plan.

⚠️  You're currently locked to the aws provider (Starter tier).
To use other cloud providers, upgrade to a higher tier.

Professional Plan

Multiple cloud providers.

Feature Access
Local k3d clusters ✅ Unlimited
Cloud providers ✅ Multiple providers
Templates All templates
Support Priority email

Best for: Teams deploying to multiple cloud environments.

Founder Plan

Full access with priority support.

Feature Access
Local k3d clusters ✅ Unlimited
Cloud providers ✅ All providers
Templates All templates + early access
Support Priority + Slack

Best for: Agencies, consultancies, power users.

Provider Access by Tier

Provider Community Starter Professional Founder
local (k3d) ✅ ✅ ✅ ✅
aws (EKS) ❌ ✅* ✅ ✅
gcp (GKE) ❌ ✅* ✅ ✅
azure (AKS) ❌ ✅* ✅ ✅
digitalocean (DOKS) ❌ ✅* ✅ ✅
linode (LKE) ❌ ❌ ✅ ✅
vultr (VKE) ❌ ❌ ✅ ✅

* Starter is locked to first provider used

Template Access by Tier

Template Community Starter+
wordpress ✅ ✅
static ✅ ✅
simplephp ✅ ✅
laravel ✅ ✅

Check available templates:

displace template list

Credential Storage

Displace stores authentication data securely in your home directory:

~/.displace/
├── auth.json           # API key (encrypted)
├── entitlements.json   # Cached subscription data
└── config.json         # User configuration

Security Considerations

  • API keys are stored with restricted file permissions (0600)
  • Entitlements are cached locally to reduce API calls
  • Cache expires after 12 hours and auto-refreshes
  • Logout removes all stored credentials

Manual Credential Removal

If needed, manually remove credentials:

rm ~/.displace/auth.json
rm ~/.displace/entitlements.json

Entitlements Caching

To reduce API calls, Displace caches your subscription entitlements locally.

Cache Behavior

Scenario Behavior
Cache valid Use cached entitlements
Cache expired (>12h) Auto-refresh from server
--refresh flag Force refresh from server
--no-cache flag Bypass cache completely

Troubleshooting Cache Issues

# View current cache status
displace auth status

# Force refresh if subscription changed
displace auth status --refresh

# Bypass cache for debugging
displace auth status --no-cache

When to Refresh

Refresh your entitlements when:

  • You upgraded your subscription
  • You added a new provider
  • Status shows stale data
  • Troubleshooting access issues

Common Workflows

First-Time Setup (Community User)

# Install Displace
curl -sSL https://raw.githubusercontent.com/displacetech/displace-cli/main/install.sh | bash

# Set up local environment (no login needed)
displace install

# Create and deploy WordPress locally
mkdir my-site && cd my-site
displace project init wordpress
displace project deploy --cluster displace-local

Upgrading to Cloud Deployment

# Login with your API key
displace auth login

# Verify subscription
displace auth status

# Configure cloud provider
displace provider aws configure

# Create cloud cluster
displace cluster create production --provider aws

# Deploy to production
displace project deploy --cluster production

Switching Accounts

# Logout from current account
displace auth logout

# Login with different API key
displace auth login

Troubleshooting

"API key validation failed"

Cause: Invalid or expired API key.

Solution:

  1. Verify key is 64 characters
  2. Check key hasn't been revoked
  3. Generate new key from dashboard

"Provider not available for your subscription"

Cause: Trying to use a provider not included in your tier.

Solution:

# Check available providers
displace auth status

# Upgrade subscription if needed
# Visit https://displace.tech

"You're locked to the X provider"

Cause: Starter tier is locked after first cloud deployment.

Solution:

  • Continue using the locked provider, OR
  • Upgrade to Professional tier for multiple providers

Cache Shows Wrong Subscription

Solution:

# Force refresh from server
displace auth status --refresh

"Failed to retrieve entitlements"

Cause: Network issue or server problem.

Solution:

# Check internet connectivity
curl -I https://api.displace.tech

# Try with fresh data
displace auth status --no-cache

# Re-login if persistent
displace auth logout
displace auth login

Related Documentation

Home

Getting Started

Providers

Templates

Development

Guides

Infrastructure

Reference

Clone this wiki locally