trackerforce/switcher-api repository overview

⁠About

Switcher API is a Feature Manager that allows you to control your application features using feature flags, also known as feature toggles, feature switches, or feature flippers. It is a cloud-based solution that provides a simple and efficient way to manage your features, enabling you to release new features to your users with confidence.

Main features:

• Easy to setup and seamless integration with your application using our lightweight Client SDKs.
• Distributed Switchers can be used across multiple applications allowing you to control features in a centralized fashion.
• Multi-environment support. Create and manage features across different environments.
• Add extra layer of verification with custom conditions using Strategies.
• Delegate Switcher criteria decision to specialized application with Switcher Relay.
• Support to multiple teams and granular access control.
• Integrate with Slack usign Switcher Slack App to enable approval workflows.
• Integrate with your CI/CD pipeline to automate feature releases and centralize feature management with Switcher GitOps.
• Detailed metrics and logs to help you to track and monitor your features.

⁠Local setup

1. npm ci
2. Add .env-cmdrc file into the project directory (use '.env-cmdrc-template')
3. Replace values such as secret keys and URLs

⁠Auth Providers

Switcher API supports multiple auth providers such as email/password-based authentication, SAML 2.0 for Single Sign-On (SSO), or GitHub/Bitbucket OAuth.

⁠GitHub OAuth App setup

1. Open your GitHub account or organization settings
2. Go to Developer settings > OAuth Apps
3. Click on "New OAuth App"
4. Fill in the application details:
   • Application name: Switcher API
   • Homepage URL: https://switcher-management-url⁠ (or your deployed URL)
   • Authorization callback URL: https://switcher-management-url/login?platform=github⁠
5. Click on "Register application"
6. Copy the Client ID and Client Secret
7. Update your .env-cmdrc file or ConfigMap/Secret in Kubernetes with the following variables:
   • GIT_OAUTH_CLIENT_ID=your_client_id
   • GIT_OAUTH_CLIENT_SECRET=your_client_secret
8. Update Switcher Management GITHUB_CLIENTID environment variable with your_client_id

⁠Bitbucket OAuth App setup

1. Open your Bitbucket account or workspace settings
2. Go to Apps and features > OAuth consumers
3. Fill in the application details:
   • Name: Switcher API
   • Callback URL: https://switcher-management-url/login?platform=bitbucket⁠
4. Add permissions -> Account: Read
5. Click on "Save"
6. Copy the Key and Secret
7. Update your .env-cmdrc file or ConfigMap/Secret in Kubernetes with the following variables:
   • BIT_OAUTH_CLIENT_ID=your_client_id
   • BIT_OAUTH_CLIENT_SECRET=your_client_secret
8. Update Switcher Management BITBUCKET_CLIENTID environment variable with your_client_id

⁠SSO with SAML 2.0 setup

1. Obtain the following information from your Identity Provider (IdP):

   • Entry Point URL
   • X.509 Certificate
   • (Optional) Private Key

2. Update your .env-cmdrc file or ConfigMap/Secret in Kubernetes with the following variables:

   • SAML_ENTRY_POINT=your_idp_entry_point_url
   • SAML_ISSUER=your_issuer
   • SAML_CALLBACK_ENDPOINT_URL=service_provider_callback_endpoint_url
   • SAML_REDIRECT_ENDPOINT_URL=web_app_redirect_endpoint_url
   • SAML_CERT=your_x509_certificate_base64_encoded
   • SAML_PRIVATE_KEY=your_private_key_base64_encoded (if applicable)
   • SAML_IDENTIFIER_FORMAT=urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
   • SAML_ACCEPTED_CLOCK_SKEW_MS=5000
   • SESSION_SECRET=SESSION_SECRET

3. Enable SAML authentication in Switcher Management by setting the environment variable SAML_ENABLE=true

• service_provider refers to Switcher API
• web_app refers to Switcher Management

⁠Dynamic OAuth clients (e.g. MCP server) consent screen

OAuth clients created via POST /oauth/register (such as switcher-mcp-server) are redirected to a browser-based consent screen hosted by Switcher Management at /oauth/consent, rather than directly to this API. Set OAUTH_CONSENT_URL to your Switcher Management public URL so the authorization_endpoint advertised at /.well-known/oauth-authorization-server points there and OAUTH_ISSUER_URL to the public URL of your Switcher API.

Optionally, set OAUTH_ALLOWED_REDIRECT_HOSTS to a comma-separated list of hostnames (e.g. claude.ai,vscode.dev) to restrict the https redirect_uri hosts accepted by /oauth/register, /oauth/authorize and /oauth/token. These are the hosts of the OAuth clients' callbacks. Loopback callbacks (127.0.0.1/localhost) are always allowed. When unset, any https host is accepted.

⁠Running Switcher API from Docker Composer manifest file

This option leverages Switcher API and Switcher Management with minimum settings required.

1. Modify the configuration file "config/.env.dev":

• JWT_SECRET: With your secure private key
• SWITCHERAPI_URL: The Switcher API URL that Switcher Management will use internally
• SM_IP: IP/DNS used by Switcher Management internal redirects

1. Run:

docker-compose --env-file ./config/.env.dev up -d

1. Open Switcher Management:

http://localhost

⁠Quick start

Open Swagger UI by accessing the URL: http://localhost:3000/api-docs⁠
Or use Postman by importing either the OpenAPI json from http://localhost:3000/swagger.json⁠ or Postman Collection from "requests/Switcher API*"

⁠API configuration

⁠Signing up

Signing up an account to use Switcher API with an email/password or linking it to a GitHub or Bitbucket account.

• Singing up via email - Admin: /admin/signup [POST]
• Singing up via GitHub - Admin: /admin/github/auth?code= [POST]
• Singing up via Bitbucket - Admin: /admin/bitbucket/auth?code= [POST]

⁠Domain

Domains are responsible for centralizing all settings and configurations.
It is equivalent to an organization that can manage multiple projects, users, and environments.

• New domain - Domain: /domain/create [POST]

⁠Component

Components are applications that will use Switcher API.
Each component has its own access API key to interact with Switcher API.

• Create a component - Component: /component/create [POST]
• Generating a new API Key - Component: /component/generateApiKey [GET]

⁠Group

Groups are used to organize Switchers that share the same feature scope.

• New Group - GroupConfig: /groupconfig/create [POST]

⁠Switcher

Switchers are the entry point to control features in your application.

• New Switcher - Config: /config/create [POST]

⁠Strategy

Customize the Switcher behavior by including strategy rules to your Switchers.

• New Strategy - ConfigStrategy: /configstrategy/create [POST]

⁠AI Disclaimer

This project's core foundation was built and maintained by a human from day one. However, we have leveraged AI tools to assist in various aspects of the development process, such as troubleshooting, code optimization, and documentation. We have thoroughly reviewed and tested all AI-generated contributions to ensure they meet our quality standards and align with our project's goals. We are committed to transparency about our use of AI and will continue to disclose any significant AI contributions in the future.

External contributions from the community are equally valued and will be reviewed with the same standards, regardless of whether they were assisted by AI or not. We encourage all contributors to disclose their use of AI tools in their contributions to maintain transparency and foster trust within our community.