agent-auth

Agent Authentication

Authenticate with the Epic FlowState gateway and configure credentials for subsequent API calls.

Steps

1. Check current auth state

   • Check if EPIC_FLOWSTATE_API_KEY is set in the environment
   • If set, verify it works:

     curl -s -H "Authorization: Bearer $EPIC_FLOWSTATE_API_KEY" \
       https://gateway.epicflowstate.com/mcp \
       -d '{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}' | jq .
     

2. CLI login (if using the CLI)

   npm install -g @epicdm/agent-cli
   epic-agent login
   # Opens browser for OAuth flow
   # Saves token to ~/.epic-agent/credentials.json
   

3. OAuth flow (for MCP clients)

   • Discovery URL: https://gateway.epicflowstate.com/.well-known/oauth-authorization-server
   • Authorization endpoint: https://gateway.epicflowstate.com/oauth/authorize
   • Token endpoint: https://gateway.epicflowstate.com/oauth/token
   • Use PKCE flow (S256 code challenge)

4. API key authentication

   • Generate a key: Account → API Keys → New Key
   • Set in environment: export EPIC_FLOWSTATE_API_KEY=eak_...
   • Pass as header: Authorization: Bearer eak_...

5. Verify credentials work

   epic-agent agents list
   # or via MCP:
   # POST https://gateway.epicflowstate.com/mcp
   # {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
   

Error handling

• 401 Unauthorized: token expired — run epic-agent login or generate new API key
• 403 Forbidden: insufficient scope — check key permissions in Account → API Keys
• EPIC_FLOWSTATE_API_KEY not set: prompt user to generate a key from the portal dashboard