Authentication

Soup supports multiple authentication methods depending on your use case.

For Humans: GitHub OAuth

The dashboard and CLI use GitHub OAuth.

Dashboard

Visit app.getsoup.dev and click “Sign in with GitHub.”

CLI - Local Machine

soup login

Opens your browser for GitHub login. Token saved to ~/.soup/config.json.

CLI - Remote/Headless

For servers or remote machines where you can’t open a browser:

soup login --device

# Output:
#   Open this URL in any browser:
#     https://app.getsoup.dev/cli/device
#   Enter this code:
#     ABCD-EFGH
#   Waiting for authentication...

1. Open the URL on your phone/laptop
2. Enter the code
3. Authorize with GitHub
4. CLI automatically continues

For APIs: Personal Access Tokens

Create tokens in the dashboard under Settings → API Tokens.

Create Token

# Via CLI
soup token create --name "CI Deploy" --scopes secrets:read,secrets:write

# Or via dashboard
Settings → API Tokens → Create Token

Scopes:

• projects:read, projects:write
• secrets:read, secrets:write, secrets:delete
• flags:read, flags:write, flags:delete
• envs:create, envs:delete

Use Token

curl https://app.getsoup.dev/api/v1/projects/my-app/environments/production/secrets \
  -H "Authorization: Bearer soup_pat_..."

Or set in CLI:

export SOUP_TOKEN=soup_pat_...
soup secrets list  # uses $SOUP_TOKEN if present

For Services: Service Accounts

Service accounts are project-scoped with specific roles.

Create Service Account

Via API (no UI yet):

POST /api/v1/service-accounts
{
  "name": "Production Deploy",
  "project_slug": "my-app",
  "role": "editor"  # or "viewer"
}

Returns a soup_sk_... token.

Roles:

• Editor: Read/write access to project
• Viewer: Read-only access

Use Service Account

Same as personal tokens:

curl -H "Authorization: Bearer soup_sk_..." \
  https://app.getsoup.dev/api/v1/projects/my-app/...

Self-Hosted: API Keys

For self-hosted Soup instances (standalone mode).

Master Key

Full access to all projects:

# Generate on first run
soup-engine --generate-master-key

# Or via API
POST /keys
{
  "name": "Master Key",
  "key_type": "master"
}

Returns sk_master_... token.

Project Key

Scoped to single project:

POST /projects/{slug}/keys
{
  "name": "My App Key"
}

Returns sk_proj_... token.

Use API Key

curl http://localhost:8080/api/v1/projects/my-app/secrets \
  -H "Authorization: Bearer sk_master_..."

Token Security

Do:

• Store tokens in env vars or secret managers
• Use project-scoped service accounts for CI/CD
• Rotate tokens regularly
• Use minimal scopes

Don’t:

• Commit tokens to git
• Share tokens between services
• Use master keys in production apps

Revoke Tokens

# Via CLI
soup token revoke <token-id>

# Or in dashboard
Settings → API Tokens → Revoke

Revoked tokens stop working immediately.