Skip to content

Authentication

Learn how to authenticate with FuncSpec across different interfaces.

Web Authentication

Account Creation

  1. Sign Up: Visit funcspec.net and click "Sign Up"
  2. Email Verification: Check your email and click the verification link
  3. Organization Setup: Create your first organization or join an existing one
  4. Two-Factor Authentication (Recommended): Enable 2FA in Account Settings

Login Methods

  • Email/Password: Standard authentication
  • Two-Factor Authentication: TOTP codes via authenticator app
  • Session Management: Sessions expire after 24 hours of inactivity

API Authentication

API Keys

API keys provide programmatic access to FuncSpec:

  1. Generate Key: Organization Settings → API Keys → "Create API Key"
  2. Name Your Key: Give it a descriptive name (e.g., "CI/CD Pipeline")
  3. Copy Key: Save it securely - it's only shown once
  4. Use in Requests: Include in the X-Api-Key header
curl -H "X-Api-Key: your-api-key-here" \
  https://funcspec.net/api/v1/projects

Key Management

  • Multiple Keys: Create separate keys for different use cases
  • Key Rotation: Regularly rotate keys for security
  • Revocation: Delete compromised keys immediately
  • Monitoring: Track API usage in Organization Settings

Rate Limits

API keys are subject to rate limiting:

  • Free Tier: 1,000 requests/hour
  • Pro: 10,000 requests/hour
  • Enterprise: Custom limits

Rate limit headers are included in responses: 

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

CLI Authentication

Initial Setup

# Login interactively
funcspec auth login

# Or set API key directly
export FUNCSPEC_API_KEY="your-api-key"
funcspec config set api_key "your-api-key"

Configuration

The CLI stores config in ~/.config/funcspec/config.toml:

api_key = "your-api-key"
base_url = "https://funcspec.net"
default_format = "table"

Multiple Profiles

Manage multiple accounts or environments:

# Set up profiles
funcspec config profile create production --api-key "prod-key"
funcspec config profile create staging --api-key "staging-key"

# Switch profiles
funcspec config profile use production

Organization Access

Membership Roles

Organizations have hierarchical access control:

  • Owner: Full organization control, billing, member management
  • Admin: Member management, organization settings (no billing)
  • Member: Project access based on project-level permissions

Project-Level Access

Each project has its own team with granular permissions:

  • Admin: Full project control, team management
  • Editor: Create, edit, and delete spec items
  • Viewer: Read-only access to specifications

Joining Organizations

  • Invitation: Organization admins can invite by email
  • Auto-creation: First user becomes organization owner
  • Multi-org: Users can be members of multiple organizations

Security Best Practices

API Keys

  • Scope: Create separate keys for different applications
  • Environment Variables: Store keys in environment variables, not code
  • CI/CD: Use secret management for automated systems
  • Rotation: Rotate keys quarterly or when team members leave

Account Security

  • Strong Passwords: Use a password manager for unique, strong passwords
  • Two-Factor Auth: Enable TOTP-based 2FA for additional security
  • Session Management: Log out from shared/public computers
  • Regular Review: Audit team access and remove unused accounts

Network Security

  • HTTPS Only: All FuncSpec communication uses TLS encryption
  • Firewall Rules: Restrict API access by IP when possible
  • VPN Access: Use VPN for additional network security
  • Audit Logging: Monitor API access patterns for anomalies

Troubleshooting

Common Issues

Invalid API Key 

HTTP 401: Unauthorized
- Check that your API key is correct - Ensure the key hasn't been revoked - Verify you're using the right organization

Rate Limited 

HTTP 429: Rate Limit Exceeded
- Reduce request frequency - Implement exponential backoff - Consider upgrading your plan

Forbidden Access 

HTTP 403: Forbidden
- Check your project permissions - Ensure you're a member of the organization - Verify the resource exists and you have access

Getting Help

  • Status Page: Check status.funcspec.net for outages
  • Documentation: Review API documentation for endpoint requirements
  • Support: Email support@funcspec.net with your API key ID (not the key itself)
  • Community: Join our Discord for community support