@lukoweb/apitogo 0.2.22 → 0.2.24

package/docs/configuration/authentication-clerk.md

@@ -1,117 +1,117 @@
----
-title: Clerk Setup
-sidebar_label: Clerk
-description:
-  Learn how to set up Clerk authentication for APIToGo, providing a seamless authentication
-  experience with modern UI components and extensive customization options.
----
-
-:::caution{title="SPA / advanced"}
-
-Portal products on APItoGo use [`dev-portal`](./authentication.md) authentication. Use Clerk SPA
-integration only for standalone docs sites that talk to Clerk directly.
-
-:::
-
-Clerk is a modern authentication platform that provides beautiful, customizable UI components and a
-developer-friendly experience. This guide walks you through integrating Clerk authentication with
-your APIToGo documentation site.
-
-## Prerequisites
-
-If you don't have a Clerk account, you can sign up for a [free Clerk account](https://clerk.com/)
-that provides 10,000 monthly active users.
-
-## Setup Steps
-
-<Stepper>
-
-1. **Create a Clerk Application**
-
-   In the [Clerk Dashboard](https://dashboard.clerk.com/):
-   - Click **Create Application**
-   - Enter your application name
-   - Select your preferred authentication methods (email, social providers, etc.)
-   - Click **Create Application**
-
-2. **Create a Clerk JWT Template** You need to create a JWT Template so your JWTs include name,
-   email and email_verified information.
-
-- Navigate to **JWT templates** in the [Clerk Dashboard](https://dashboard.clerk.com/)
-- Create a new template by clicking **Add new template**
-- Pick a name for the template
-- Add the following claims
-  ```json
-  {
-    "name": "{{user.full_name}}",
-    "email": "{{user.primary_email_address}}",
-    "email_verified": "{{user.email_verified}}"
-  }
-  ```
-- Save
-
-3. **Configure APIToGo**
-
-   Get your publishable key from the Clerk dashboard:
-   - Navigate to **API Keys** in your Clerk dashboard
-   - Copy the **Publishable key**
-
-   Use the JWT template name defined in the previous section
-
-   Add the Clerk configuration to your [APIToGo configuration file](./overview.md):
-
-   ```typescript
-   // site config
-   export default {
-     // ... other configuration
-     authentication: {
-       type: "clerk",
-       clerkPubKey: "<your-clerk-publishable-key>",
-       jwtTemplateName: "<your-clerk-jwt-template-name>",
-     },
-     // ... other configuration
-   };
-   ```
-
-4. **Configure Redirect URLs (Optional)**
-
-   If you need custom redirect behavior, configure the allowed redirect URLs in Clerk:
-   - Go to **Paths** in your Clerk dashboard
-   - Add your production, preview, and local development URLs to the allowed redirect URLs
-   - Common patterns:
-     - Production: `https://your-site.com/oauth/callback`
-     - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
-     - Local Development: `http://localhost:3000/oauth/callback`
-
-5. **Install Clerk Dependencies**
-
-   Add `@clerk/clerk-js` to your project dependencies:
-
-   ```bash
-   npm install @clerk/clerk-js
-   ```
-
-   </Stepper>
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Invalid Publishable Key**: Ensure you're using the publishable key (starts with `pk_`) and not
-   the secret key.
-
-2. **Authentication Not Working**: Verify that your Clerk application is active and not in
-   development mode when deploying to production.
-
-3. **Redirect Issues**: Check that your domain is added to the allowed redirect URLs in Clerk if
-   using custom redirects.
-
-4. **ReferenceError: can't access lexical declaration 'xxx' before initialization**: Make sure you
-   have installed Clerk to your project.
-
-## Next Steps
-
-- Explore [Clerk's documentation](https://clerk.com/docs) for advanced features
-- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
-- Configure [user roles and permissions](https://clerk.com/docs/organizations/roles-permissions) in
-  Clerk
+---
+title: Clerk Setup
+sidebar_label: Clerk
+description:
+  Learn how to set up Clerk authentication for APIToGo, providing a seamless authentication
+  experience with modern UI components and extensive customization options.
+---
+
+:::caution{title="SPA / advanced"}
+
+Portal products on APItoGo use [`dev-portal`](./authentication.md) authentication. Use Clerk SPA
+integration only for standalone docs sites that talk to Clerk directly.
+
+:::
+
+Clerk is a modern authentication platform that provides beautiful, customizable UI components and a
+developer-friendly experience. This guide walks you through integrating Clerk authentication with
+your APIToGo documentation site.
+
+## Prerequisites
+
+If you don't have a Clerk account, you can sign up for a [free Clerk account](https://clerk.com/)
+that provides 10,000 monthly active users.
+
+## Setup Steps
+
+<Stepper>
+
+1. **Create a Clerk Application**
+
+   In the [Clerk Dashboard](https://dashboard.clerk.com/):
+   - Click **Create Application**
+   - Enter your application name
+   - Select your preferred authentication methods (email, social providers, etc.)
+   - Click **Create Application**
+
+2. **Create a Clerk JWT Template** You need to create a JWT Template so your JWTs include name,
+   email and email_verified information.
+
+- Navigate to **JWT templates** in the [Clerk Dashboard](https://dashboard.clerk.com/)
+- Create a new template by clicking **Add new template**
+- Pick a name for the template
+- Add the following claims
+  ```json
+  {
+    "name": "{{user.full_name}}",
+    "email": "{{user.primary_email_address}}",
+    "email_verified": "{{user.email_verified}}"
+  }
+  ```
+- Save
+
+3. **Configure APIToGo**
+
+   Get your publishable key from the Clerk dashboard:
+   - Navigate to **API Keys** in your Clerk dashboard
+   - Copy the **Publishable key**
+
+   Use the JWT template name defined in the previous section
+
+   Add the Clerk configuration to your [APIToGo configuration file](./overview.md):
+
+   ```typescript
+   // site config
+   export default {
+     // ... other configuration
+     authentication: {
+       type: "clerk",
+       clerkPubKey: "<your-clerk-publishable-key>",
+       jwtTemplateName: "<your-clerk-jwt-template-name>",
+     },
+     // ... other configuration
+   };
+   ```
+
+4. **Configure Redirect URLs (Optional)**
+
+   If you need custom redirect behavior, configure the allowed redirect URLs in Clerk:
+   - Go to **Paths** in your Clerk dashboard
+   - Add your production, preview, and local development URLs to the allowed redirect URLs
+   - Common patterns:
+     - Production: `https://your-site.com/oauth/callback`
+     - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
+     - Local Development: `http://localhost:3000/oauth/callback`
+
+5. **Install Clerk Dependencies**
+
+   Add `@clerk/clerk-js` to your project dependencies:
+
+   ```bash
+   npm install @clerk/clerk-js
+   ```
+
+   </Stepper>
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Invalid Publishable Key**: Ensure you're using the publishable key (starts with `pk_`) and not
+   the secret key.
+
+2. **Authentication Not Working**: Verify that your Clerk application is active and not in
+   development mode when deploying to production.
+
+3. **Redirect Issues**: Check that your domain is added to the allowed redirect URLs in Clerk if
+   using custom redirects.
+
+4. **ReferenceError: can't access lexical declaration 'xxx' before initialization**: Make sure you
+   have installed Clerk to your project.
+
+## Next Steps
+
+- Explore [Clerk's documentation](https://clerk.com/docs) for advanced features
+- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
+- Configure [user roles and permissions](https://clerk.com/docs/organizations/roles-permissions) in
+  Clerk

package/docs/configuration/authentication-firebase.md

@@ -1,69 +1,69 @@
----
-title: Firebase Setup
-sidebar_label: Firebase
-description:
-  Learn how to set up Firebase Authentication for APIToGo, leveraging Google's secure authentication
-  infrastructure with multiple sign-in providers.
----
-
-:::caution{title="SPA / advanced"}
-
-Portal products on APItoGo use [`dev-portal`](./authentication.md) authentication. Use Firebase SPA
-integration only for standalone docs sites that talk to Firebase directly.
-
-:::
-
-Firebase Authentication provides a comprehensive identity solution from Google, supporting
-email/password authentication and federated identity providers like Google, Facebook, Twitter, and
-more. This guide shows you how to integrate Firebase Authentication with your APIToGo documentation
-site.
-
-## Prerequisites
-
-- A Google account to access Firebase Console
-- A Firebase project (free tier available)
-- Basic knowledge of Firebase configuration
-
-## Setup Firebase
-
-1. Go to the [Firebase Console](https://console.firebase.google.com/):
-2. Click **Create a project** (or select an existing project)
-3. Make sure authentication is enabled. Choose your preferred authentication providers.
-4. Configure Authorized Domains, add your domains where the authentication will be used.
-5. **Get Your Firebase Configuration**
-   - Go to **Project settings**
-   - Scroll to **Your apps** section
-   - Click **Add app** → **Web** if you haven't already
-   - Register your app with a nickname
-   - Copy the Firebase configuration object
-
-## Configure APIToGo
-
-Add the Firebase configuration to your [APIToGo configuration file](./overview.md):
-
-```typescript title="config"
-export default {
-  authentication: {
-    type: "firebase",
-    // Replace these with your Firebase project configuration
-    // Get these values from Firebase Console > Project Settings
-    apiKey: "<insert your API key here>",
-    authDomain: "your-domain.firebaseapp.com",
-    projectId: "your-project-id",
-    appId: "1:296819355813:web:91d29f11cac6f073595d4c",
-    // Optional fields
-    storageBucket: "your-project.firebasestorage.app",
-    messagingSenderId: "296819355813",
-    measurementId: "G-12W6TTNR75",
-    // Optional: specify which providers to show in the sign-in UI
-    // Available providers: "google", "github", "facebook", "twitter",
-    // "microsoft", "apple", "yahoo", "password", "phone"
-    // If not specified, all enabled providers in Firebase will be available
-    providers: ["google", "github", "password"],
-    // Optional: configure redirect URLs after authentication
-    redirectToAfterSignIn: "/docs",
-    redirectToAfterSignUp: "/getting-started",
-    redirectToAfterSignOut: "/",
-  },
-};
-```
+---
+title: Firebase Setup
+sidebar_label: Firebase
+description:
+  Learn how to set up Firebase Authentication for APIToGo, leveraging Google's secure authentication
+  infrastructure with multiple sign-in providers.
+---
+
+:::caution{title="SPA / advanced"}
+
+Portal products on APItoGo use [`dev-portal`](./authentication.md) authentication. Use Firebase SPA
+integration only for standalone docs sites that talk to Firebase directly.
+
+:::
+
+Firebase Authentication provides a comprehensive identity solution from Google, supporting
+email/password authentication and federated identity providers like Google, Facebook, Twitter, and
+more. This guide shows you how to integrate Firebase Authentication with your APIToGo documentation
+site.
+
+## Prerequisites
+
+- A Google account to access Firebase Console
+- A Firebase project (free tier available)
+- Basic knowledge of Firebase configuration
+
+## Setup Firebase
+
+1. Go to the [Firebase Console](https://console.firebase.google.com/):
+2. Click **Create a project** (or select an existing project)
+3. Make sure authentication is enabled. Choose your preferred authentication providers.
+4. Configure Authorized Domains, add your domains where the authentication will be used.
+5. **Get Your Firebase Configuration**
+   - Go to **Project settings**
+   - Scroll to **Your apps** section
+   - Click **Add app** → **Web** if you haven't already
+   - Register your app with a nickname
+   - Copy the Firebase configuration object
+
+## Configure APIToGo
+
+Add the Firebase configuration to your [APIToGo configuration file](./overview.md):
+
+```typescript title="config"
+export default {
+  authentication: {
+    type: "firebase",
+    // Replace these with your Firebase project configuration
+    // Get these values from Firebase Console > Project Settings
+    apiKey: "<insert your API key here>",
+    authDomain: "your-domain.firebaseapp.com",
+    projectId: "your-project-id",
+    appId: "1:296819355813:web:91d29f11cac6f073595d4c",
+    // Optional fields
+    storageBucket: "your-project.firebasestorage.app",
+    messagingSenderId: "296819355813",
+    measurementId: "G-12W6TTNR75",
+    // Optional: specify which providers to show in the sign-in UI
+    // Available providers: "google", "github", "facebook", "twitter",
+    // "microsoft", "apple", "yahoo", "password", "phone"
+    // If not specified, all enabled providers in Firebase will be available
+    providers: ["google", "github", "password"],
+    // Optional: configure redirect URLs after authentication
+    redirectToAfterSignIn: "/docs",
+    redirectToAfterSignUp: "/getting-started",
+    redirectToAfterSignOut: "/",
+  },
+};
+```

package/docs/configuration/authentication-pingfederate.md

@@ -1,143 +1,143 @@
----
-title: PingFederate Setup
-sidebar_label: PingFederate
-description:
-  Learn how to set up PingFederate authentication for APIToGo using OpenID Connect for
-  enterprise-grade single sign-on.
----
-
-:::caution{title="SPA / advanced"}
-
-Portal products on APItoGo use [`dev-portal`](./authentication.md) authentication. Use PingFederate
-SPA integration only for standalone docs sites that talk to PingFederate directly.
-
-:::
-
-PingFederate is an enterprise federation server that enables secure single sign-on (SSO) and API
-security for organizations. This guide walks you through integrating PingFederate with APIToGo using
-OpenID Connect.
-
-## Prerequisites
-
-- Access to a PingFederate server (version 9.0 or later recommended)
-- Administrative access to configure OAuth clients in PingFederate
-- Your PingFederate server's base URL
-
-## Setup Steps
-
-<Stepper>
-
-1. **Create an OAuth Client in PingFederate**
-
-   In the PingFederate administrative console:
-   - Navigate to **Applications** → **OAuth** → **Clients**
-   - Click **Add Client**
-   - Configure the client:
-     - **Client ID**: Choose a unique identifier (e.g., `apitogo-docs`)
-     - **Client Authentication**: Select **None (Public Client)**
-     - **Grant Types**: Enable **Authorization Code** and **Refresh Token**
-     - **Redirect URIs**:
-       - Production: `https://your-site.com/oauth/callback`
-       - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
-       - Local Development: `http://localhost:3000/oauth/callback`
-
-2. **Configure OpenID Connect Settings**
-
-   Still in the OAuth client configuration:
-   - Enable **OpenID Connect**
-   - Configure scopes:
-     - Enable `openid`, `profile`, and `email` (minimum required)
-     - Add any custom scopes your organization requires
-   - **ID Token Signing Algorithm**: RS256 (recommended)
-   - **Access Token Manager**: Select or create an appropriate token manager
-   - Save the configuration
-
-3. **Configure APIToGo**
-
-   Add the PingFederate configuration to your [APIToGo configuration file](./overview.md):
-
-   ```typescript
-   // site config
-   export default {
-     // ... other configuration
-     authentication: {
-       type: "openid",
-       clientId: "apitogo-docs", // Your OAuth client ID
-       issuer: "https://pingfederate.your-domain.com", // Your PingFederate base URL
-       scopes: ["openid", "profile", "email"], // Optional: add custom scopes
-     },
-     // ... other configuration
-   };
-   ```
-
-</Stepper>
-
-## Configuration Options
-
-### Custom Scopes
-
-If your organization uses custom scopes for authorization, include them in the configuration:
-
-```typescript
-authentication: {
-  type: "openid",
-  clientId: "apitogo-docs",
-  issuer: "https://pingfederate.your-domain.com",
-  scopes: ["openid", "profile", "email", "groups", "roles", "api:read"],
-}
-```
-
-## Advanced Configuration
-
-### CORS Configuration
-
-Configure CORS in PingFederate for your documentation site:
-
-1. Navigate to **System** → **Server Configuration** → **Cross-Origin Resource Sharing**
-2. Add your site's domain to the allowed origins:
-   - `https://your-site.com`
-   - `http://localhost:3000` (for local development)
-
-### Attribute Mapping
-
-PingFederate can map user attributes from various sources. Ensure these standard claims are mapped:
-
-1. Go to **OAuth** → **Access Token Management** → **Your Token Manager**
-2. Configure attribute mappings:
-   - `sub` → User's unique identifier
-   - `name` → User's display name
-   - `email` → User's email address
-   - `picture` → User's profile picture URL (if available)
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Discovery Endpoint Not Found**: Ensure your issuer URL is correct and accessible. The OpenID
-   Connect discovery endpoint should be available at
-   `https://your-pingfederate-server/.well-known/openid-configuration`.
-
-2. **Invalid Client Configuration**: Verify that the client ID matches exactly and that the redirect
-   URIs are properly configured in PingFederate.
-
-3. **CORS Errors**: Check that your site's domain is added to PingFederate's CORS configuration.
-
-4. **Missing User Attributes**: Ensure attribute mappings are configured in your Access Token
-   Manager.
-
-5. **Token Validation Errors**: Verify that your PingFederate server's certificates are valid and
-   that clock synchronization is accurate.
-
-## Security Considerations
-
-- Always use HTTPS for production deployments
-- Regularly rotate signing certificates in PingFederate
-- Configure appropriate session timeouts
-- Review and audit OAuth client configurations periodically
-
-## Next Steps
-
-- Review [PingFederate documentation](https://docs.pingidentity.com/pingfederate/) for advanced
-  features
-- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
-- Configure group-based access control using PingFederate claims
+---
+title: PingFederate Setup
+sidebar_label: PingFederate
+description:
+  Learn how to set up PingFederate authentication for APIToGo using OpenID Connect for
+  enterprise-grade single sign-on.
+---
+
+:::caution{title="SPA / advanced"}
+
+Portal products on APItoGo use [`dev-portal`](./authentication.md) authentication. Use PingFederate
+SPA integration only for standalone docs sites that talk to PingFederate directly.
+
+:::
+
+PingFederate is an enterprise federation server that enables secure single sign-on (SSO) and API
+security for organizations. This guide walks you through integrating PingFederate with APIToGo using
+OpenID Connect.
+
+## Prerequisites
+
+- Access to a PingFederate server (version 9.0 or later recommended)
+- Administrative access to configure OAuth clients in PingFederate
+- Your PingFederate server's base URL
+
+## Setup Steps
+
+<Stepper>
+
+1. **Create an OAuth Client in PingFederate**
+
+   In the PingFederate administrative console:
+   - Navigate to **Applications** → **OAuth** → **Clients**
+   - Click **Add Client**
+   - Configure the client:
+     - **Client ID**: Choose a unique identifier (e.g., `apitogo-docs`)
+     - **Client Authentication**: Select **None (Public Client)**
+     - **Grant Types**: Enable **Authorization Code** and **Refresh Token**
+     - **Redirect URIs**:
+       - Production: `https://your-site.com/oauth/callback`
+       - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
+       - Local Development: `http://localhost:3000/oauth/callback`
+
+2. **Configure OpenID Connect Settings**
+
+   Still in the OAuth client configuration:
+   - Enable **OpenID Connect**
+   - Configure scopes:
+     - Enable `openid`, `profile`, and `email` (minimum required)
+     - Add any custom scopes your organization requires
+   - **ID Token Signing Algorithm**: RS256 (recommended)
+   - **Access Token Manager**: Select or create an appropriate token manager
+   - Save the configuration
+
+3. **Configure APIToGo**
+
+   Add the PingFederate configuration to your [APIToGo configuration file](./overview.md):
+
+   ```typescript
+   // site config
+   export default {
+     // ... other configuration
+     authentication: {
+       type: "openid",
+       clientId: "apitogo-docs", // Your OAuth client ID
+       issuer: "https://pingfederate.your-domain.com", // Your PingFederate base URL
+       scopes: ["openid", "profile", "email"], // Optional: add custom scopes
+     },
+     // ... other configuration
+   };
+   ```
+
+</Stepper>
+
+## Configuration Options
+
+### Custom Scopes
+
+If your organization uses custom scopes for authorization, include them in the configuration:
+
+```typescript
+authentication: {
+  type: "openid",
+  clientId: "apitogo-docs",
+  issuer: "https://pingfederate.your-domain.com",
+  scopes: ["openid", "profile", "email", "groups", "roles", "api:read"],
+}
+```
+
+## Advanced Configuration
+
+### CORS Configuration
+
+Configure CORS in PingFederate for your documentation site:
+
+1. Navigate to **System** → **Server Configuration** → **Cross-Origin Resource Sharing**
+2. Add your site's domain to the allowed origins:
+   - `https://your-site.com`
+   - `http://localhost:3000` (for local development)
+
+### Attribute Mapping
+
+PingFederate can map user attributes from various sources. Ensure these standard claims are mapped:
+
+1. Go to **OAuth** → **Access Token Management** → **Your Token Manager**
+2. Configure attribute mappings:
+   - `sub` → User's unique identifier
+   - `name` → User's display name
+   - `email` → User's email address
+   - `picture` → User's profile picture URL (if available)
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Discovery Endpoint Not Found**: Ensure your issuer URL is correct and accessible. The OpenID
+   Connect discovery endpoint should be available at
+   `https://your-pingfederate-server/.well-known/openid-configuration`.
+
+2. **Invalid Client Configuration**: Verify that the client ID matches exactly and that the redirect
+   URIs are properly configured in PingFederate.
+
+3. **CORS Errors**: Check that your site's domain is added to PingFederate's CORS configuration.
+
+4. **Missing User Attributes**: Ensure attribute mappings are configured in your Access Token
+   Manager.
+
+5. **Token Validation Errors**: Verify that your PingFederate server's certificates are valid and
+   that clock synchronization is accurate.
+
+## Security Considerations
+
+- Always use HTTPS for production deployments
+- Regularly rotate signing certificates in PingFederate
+- Configure appropriate session timeouts
+- Review and audit OAuth client configurations periodically
+
+## Next Steps
+
+- Review [PingFederate documentation](https://docs.pingidentity.com/pingfederate/) for advanced
+  features
+- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
+- Configure group-based access control using PingFederate claims