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

Supported services include:

AI & Language Models: OpenAI, Anthropic, Claude, OpenRouter

Code & Git: GitHub, GitLab, AWS (IAM/SSO)

Design & Productivity: Figma, Linear, Notion, Slack, Discord

Email & Marketing: Loops, SendGrid, Resend

Infrastructure & Database: Supabase, Vercel, Fly, Cloudflare

E-commerce & Streaming: Shopify, Spotify, Twitch, Zoom, Dropbox

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, and documentation
• 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
• notes: Additional documentation for non-standard auth flows

API Object

Each API in apis contains:

• base_url: Base URL for API requests
• auth_header: Authorization header template (e.g., Authorization: Bearer {token})
• docs_url: Link to API documentation
• spec_url: Link to OpenAPI/GraphQL spec (optional)
• spec_type: Type of spec (openapi or graphql)
• example_endpoint: Example API endpoint path (optional)
• variables: Parameters for parameterized URLs (optional)
• methods: List of auth methods supported by this API

Method Object

Each method in methods contains:

• label: Human-readable name for the method
• endpoints: OAuth endpoints (authorize, token, device_authorization)
• scope: OAuth scopes (comma-separated string or array)
• register: Setup instructions with url and steps array
• script: Interactive steps for the auth flow
• dynamic_registration: MCP OAuth dynamic registration settings

Client Object

Each client in clients contains:

• name: Client name/identifier
• id: OAuth client ID (use YOUR_CLIENT_ID for placeholders)
• secret: OAuth client secret (empty for public clients)
• type: Client type (public, installed, confidential)
• source: Link to source code or documentation
• methods: Array of supported auth methods

Identity Object

Identity hints for multi-account support:

• label: Field label (e.g., Account, Workspace)
• hint: Placeholder text to guide the user

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.