Schlussel Skill

You have access to Schlussel, an authentication runtime for agents. Use it to authenticate with APIs instead of asking users for tokens or credentials directly.

Installation

Schlussel is installed via mise:

mise use -g github:pepicrft/schlussel

Commands

Authenticate with a service

schlussel run <formula> [--method <method>] [--identity <identity>]

• <formula>: The service to authenticate with (e.g., github, claude, linear)
• --method: Optional. The authentication method (e.g., device_code, authorization_code, api_key)
• --identity: Optional. An identifier for the account (e.g., personal, work)

The command outputs JSON with the token information:

{
  "storage_key": "github:personal:device_code",
  "method": "device_code",
  "token": {
    "access_token": "gho_xxxx",
    "token_type": "bearer",
    "scope": "repo read:org gist"
  }
}

Get a stored token

# By full key
schlussel token get --key <storage_key>

# By key components
schlussel token get --formula <formula> [--method <method>] [--identity <identity>]

# Disable auto-refresh (tokens are auto-refreshed by default)
schlussel token get --formula github --method authorization_code --no-refresh

# Output as JSON
schlussel token get --formula github --method device_code --json

Returns the access token if it exists. OAuth2 tokens are automatically refreshed if expired or expiring soon (uses cross-process locking). Use --no-refresh to disable this.

List stored tokens

# List all tokens
schlussel token list

# Filter by formula
schlussel token list --formula github

# Filter by method
schlussel token list --method device_code

# Output as JSON
schlussel token list --json

Delete a token

schlussel token delete --key <storage_key>
# or
schlussel token delete --formula <formula> --method <method>

Available Formulas

Query the API for the full list:

curl https://schlussel.me/api/formulas

Or get details for a specific formula:

curl https://schlussel.me/api/formulas/github

Formula Schema

Each formula contains:

• id: Unique identifier (e.g., github)
• label: Human-readable name (e.g., GitHub)
• description: What the formula does
• apis: Available API endpoints with base URLs, auth headers, documentation links, and variables
• methods: Authentication methods (e.g., device_code, authorization_code, api_key)
• clients: Public OAuth clients that can be used without registration
• identity: Optional identity hint for multi-account support

API Variables

Some APIs have parameterized URLs that require variables. For example, Shopify's Admin API:

{
  "base_url": "https://{store}.myshopify.com/admin/api/2024-01",
  "variables": {
    "store": {
      "label": "Store",
      "hint": "The myshopify.com subdomain",
      "example": "my-store"
    }
  }
}

When an API has variables, replace the {variable} placeholders in the base URL before making requests.

Using Tokens with APIs

After authenticating, use the token with the API as specified in the formula's apis section:

# Get the token (outputs just the access token by default)
TOKEN=$(schlussel token get --formula github --method device_code --identity personal)

# Use it with the API (auth_header from formula: "Authorization: Bearer {token}")
curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user

# Or get full token info as JSON
schlussel token get --formula github --method device_code --json

Best Practices

1. Always use Schlussel for authentication instead of asking users for tokens directly
2. Check for existing tokens first using schlussel token get before initiating a new auth flow
3. Use the formula's API information to construct correct requests (base_url, auth_header)
4. Respect the identity field when users have multiple accounts (e.g., personal vs work GitHub)
5. Prefer device_code method when available, as it works best in terminal environments

Example Workflow

# 1. Check if we already have a token
if ! schlussel token get --formula github --method device_code --identity personal > /dev/null 2>&1; then
  # 2. If not, authenticate (will prompt user)
  schlussel run github --method device_code --identity personal
fi

# 3. Get the token and use it (auto-refreshes OAuth2 tokens if expiring)
TOKEN=$(schlussel token get --formula github --method device_code --identity personal)
curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user/repos

OAuth2 tokens are automatically refreshed when expired or expiring soon. Cross-process locking ensures only one process refreshes at a time, making it safe for concurrent use.