@lukoweb/apitogo 0.2.22 → 0.2.24

package/docs/configuration/authentication-auth0.md

@@ -1,181 +1,181 @@
----
-title: Auth0 Setup
-sidebar_label: Auth0
-description:
-  Learn how to set up Auth0 authentication for APIToGo, including application configuration and
-  integration steps for secure API documentation access.
----
-
-:::caution{title="SPA / advanced"}
-
-Portal products on APItoGo use [`dev-portal`](./authentication.md) authentication. Use Auth0 SPA
-integration only for standalone docs sites that talk to Auth0 directly.
-
-:::
-
-Auth0 is a flexible authentication and authorization platform that integrates seamlessly with
-APIToGo. This guide walks you through setting up Auth0 authentication for your documentation site.
-
-## Prerequisites
-
-If you don't have an Auth0 account, you can sign up for a
-[free Auth0 account](https://auth0.com/signup) that provides 7,000 monthly active users.
-
-## Setup Steps
-
-<Stepper>
-
-1. **Create Auth0 Application**
-
-   [Create a new Auth0 application](https://auth0.com/docs/get-started/auth0-overview/create-applications)
-   in the Auth0 dashboard:
-   - Select type **Single Page Web Applications**
-   - Give your application a descriptive name
-
-2. **Configure Auth0 Application**
-
-   In your Auth0 application settings, configure the following:
-
-   **Application URLs:**
-   - **Allowed Callback URLs**:
-     - Production: `https://your-site.com/oauth/callback`
-     - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
-     - Local Development: `http://localhost:3000/oauth/callback`
-   - **Allowed Logout URLs**: Same as callback URLs above
-
-   - **Allowed Web Origins**:
-     - Production: `https://your-site.com`
-     - Preview (wildcard): `https://*.your-domain.com`
-     - Local development: `http://localhost:3000`
-
-   **Refresh Token Rotation:**
-   - **Allow Refresh Token Rotation**: Enabled
-   - **Rotation Overlap Period**: 0 seconds (recommended)
-
-   Keep the default **Refresh Token Expiration** settings unless you have specific requirements.
-
-3. Create an Auth0 API:
-   - Navigate to the [APIs section](https://manage.auth0.com/#/apis) in the Auth0 dashboard
-   - Click **Create API**
-   - Set a name (e.g., "APIToGo API") and an identifier (e.g., `https://your-domain.com/api`)
-   - Choose **RS256** as the signing algorithm
-   - Save the API
-
-   :::warning
-
-   This step is important. If you skip creating an API, APIToGo will not be able to validate the
-   tokens issued by Auth0, leading to authentication failures.
-
-   :::
-
-4. **Configure APIToGo**
-
-   Add the Auth0 configuration to your [APIToGo configuration file](./overview.md):
-
-   ```typescript
-   // site config
-   export default {
-     // ... other configuration
-     authentication: {
-       type: "auth0",
-       domain: "your-domain.us.auth0.com",
-       clientId: "<your-auth0-client-id>",
-       audience: "https://your-domain.com/api", // Your Auth0 API identifier
-     },
-     // ... other configuration
-   };
-   ```
-
-   Where:
-   - **domain**: Your Auth0 domain (found in your application's Basic Information)
-   - **clientId**: The Client ID from your Auth0 application settings
-   - **audience**: The identifier of the Auth0 API you created (e.g., `https://your-domain.com/api`)
-
-</Stepper>
-
-## Advanced Configuration
-
-### Custom Scopes
-
-If you need additional scopes for your API access, you can specify them in the configuration:
-
-```typescript
-authentication: {
-  type: "auth0",
-  domain: "your-domain.us.auth0.com",
-  clientId: "<your-auth0-client-id>",
-  scopes: ["openid", "profile", "email", "read:api", "write:api"],
-}
-```
-
-### Enabling Logout
-
-APIToGo supports logout functionality for Auth0 tenants. For tenants created **on or after November
-14, 2023**, logout is automatically enabled through the OIDC
-[RP-Initiated Logout](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0)
-endpoint.
-
-To enable logout for your Auth0 application:
-
-1. Ensure your **Allowed Logout URLs** are configured in Auth0 (see
-   [Configure Auth0 Application](#setup-steps) above)
-2. The logout URL should match your callback URL pattern (e.g., `https://your-site.com/` for
-   production)
-
-For older tenants, you may need to enable **RP-Initiated Logout** in your tenant settings. See the
-[Auth0 logout documentation](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0)
-for details.
-
-### Customizing the Prompt Parameter
-
-By default, APIToGo sets `prompt="login"` in the Auth0 authorization request, which forces users to
-re-enter their credentials even if they have a valid session. You can customize this behavior using
-the `options.prompt` configuration:
-
-```typescript
-authentication: {
-  type: "auth0",
-  domain: "your-domain.us.auth0.com",
-  clientId: "<your-auth0-client-id>",
-  audience: "https://your-domain.com/api",
-  options: {
-    prompt: "", // Omit the prompt parameter to allow silent authentication
-  },
-}
-```
-
-Valid values for the `prompt` parameter include:
-
-- `"login"` - Force users to re-enter their credentials even if they have a valid session (default)
-- `"consent"` - Force users to consent to authorization even if they previously consented
-- `"select_account"` - Force users to select an account (useful for multi-account scenarios)
-- `"none"` - No prompt is shown; silent authentication only
-- `""` (empty string) - Omit the prompt parameter, allowing Auth0 to handle authentication based on
-  session state
-
-When the prompt parameter is omitted (empty string), Auth0 will:
-
-- Silently authenticate the user if they have a valid session
-- Redirect to the login page if no valid session exists
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Callback URL Mismatch**: Ensure your callback URLs in Auth0 exactly match your site's URL,
-   including the `/oauth/callback` path.
-
-2. **CORS Errors**: Add your site's domain to the Allowed Web Origins in Auth0.
-
-3. **Authentication Loop**: Check that your Auth0 domain includes the protocol (`https://`) but no
-   trailing slash.
-
-4. **Token Validation Errors**: Ensure the audience in your APIToGo configuration matches the
-   identifier of the Auth0 API you created.
-
-## Next Steps
-
-- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
-- Explore other [authentication providers](./authentication.md#authentication-providers) supported
-  by APIToGo
-- Configure [user permissions](./authentication.md#user-data) based on Auth0 roles
+---
+title: Auth0 Setup
+sidebar_label: Auth0
+description:
+  Learn how to set up Auth0 authentication for APIToGo, including application configuration and
+  integration steps for secure API documentation access.
+---
+
+:::caution{title="SPA / advanced"}
+
+Portal products on APItoGo use [`dev-portal`](./authentication.md) authentication. Use Auth0 SPA
+integration only for standalone docs sites that talk to Auth0 directly.
+
+:::
+
+Auth0 is a flexible authentication and authorization platform that integrates seamlessly with
+APIToGo. This guide walks you through setting up Auth0 authentication for your documentation site.
+
+## Prerequisites
+
+If you don't have an Auth0 account, you can sign up for a
+[free Auth0 account](https://auth0.com/signup) that provides 7,000 monthly active users.
+
+## Setup Steps
+
+<Stepper>
+
+1. **Create Auth0 Application**
+
+   [Create a new Auth0 application](https://auth0.com/docs/get-started/auth0-overview/create-applications)
+   in the Auth0 dashboard:
+   - Select type **Single Page Web Applications**
+   - Give your application a descriptive name
+
+2. **Configure Auth0 Application**
+
+   In your Auth0 application settings, configure the following:
+
+   **Application URLs:**
+   - **Allowed Callback URLs**:
+     - Production: `https://your-site.com/oauth/callback`
+     - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
+     - Local Development: `http://localhost:3000/oauth/callback`
+   - **Allowed Logout URLs**: Same as callback URLs above
+
+   - **Allowed Web Origins**:
+     - Production: `https://your-site.com`
+     - Preview (wildcard): `https://*.your-domain.com`
+     - Local development: `http://localhost:3000`
+
+   **Refresh Token Rotation:**
+   - **Allow Refresh Token Rotation**: Enabled
+   - **Rotation Overlap Period**: 0 seconds (recommended)
+
+   Keep the default **Refresh Token Expiration** settings unless you have specific requirements.
+
+3. Create an Auth0 API:
+   - Navigate to the [APIs section](https://manage.auth0.com/#/apis) in the Auth0 dashboard
+   - Click **Create API**
+   - Set a name (e.g., "APIToGo API") and an identifier (e.g., `https://your-domain.com/api`)
+   - Choose **RS256** as the signing algorithm
+   - Save the API
+
+   :::warning
+
+   This step is important. If you skip creating an API, APIToGo will not be able to validate the
+   tokens issued by Auth0, leading to authentication failures.
+
+   :::
+
+4. **Configure APIToGo**
+
+   Add the Auth0 configuration to your [APIToGo configuration file](./overview.md):
+
+   ```typescript
+   // site config
+   export default {
+     // ... other configuration
+     authentication: {
+       type: "auth0",
+       domain: "your-domain.us.auth0.com",
+       clientId: "<your-auth0-client-id>",
+       audience: "https://your-domain.com/api", // Your Auth0 API identifier
+     },
+     // ... other configuration
+   };
+   ```
+
+   Where:
+   - **domain**: Your Auth0 domain (found in your application's Basic Information)
+   - **clientId**: The Client ID from your Auth0 application settings
+   - **audience**: The identifier of the Auth0 API you created (e.g., `https://your-domain.com/api`)
+
+</Stepper>
+
+## Advanced Configuration
+
+### Custom Scopes
+
+If you need additional scopes for your API access, you can specify them in the configuration:
+
+```typescript
+authentication: {
+  type: "auth0",
+  domain: "your-domain.us.auth0.com",
+  clientId: "<your-auth0-client-id>",
+  scopes: ["openid", "profile", "email", "read:api", "write:api"],
+}
+```
+
+### Enabling Logout
+
+APIToGo supports logout functionality for Auth0 tenants. For tenants created **on or after November
+14, 2023**, logout is automatically enabled through the OIDC
+[RP-Initiated Logout](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0)
+endpoint.
+
+To enable logout for your Auth0 application:
+
+1. Ensure your **Allowed Logout URLs** are configured in Auth0 (see
+   [Configure Auth0 Application](#setup-steps) above)
+2. The logout URL should match your callback URL pattern (e.g., `https://your-site.com/` for
+   production)
+
+For older tenants, you may need to enable **RP-Initiated Logout** in your tenant settings. See the
+[Auth0 logout documentation](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0)
+for details.
+
+### Customizing the Prompt Parameter
+
+By default, APIToGo sets `prompt="login"` in the Auth0 authorization request, which forces users to
+re-enter their credentials even if they have a valid session. You can customize this behavior using
+the `options.prompt` configuration:
+
+```typescript
+authentication: {
+  type: "auth0",
+  domain: "your-domain.us.auth0.com",
+  clientId: "<your-auth0-client-id>",
+  audience: "https://your-domain.com/api",
+  options: {
+    prompt: "", // Omit the prompt parameter to allow silent authentication
+  },
+}
+```
+
+Valid values for the `prompt` parameter include:
+
+- `"login"` - Force users to re-enter their credentials even if they have a valid session (default)
+- `"consent"` - Force users to consent to authorization even if they previously consented
+- `"select_account"` - Force users to select an account (useful for multi-account scenarios)
+- `"none"` - No prompt is shown; silent authentication only
+- `""` (empty string) - Omit the prompt parameter, allowing Auth0 to handle authentication based on
+  session state
+
+When the prompt parameter is omitted (empty string), Auth0 will:
+
+- Silently authenticate the user if they have a valid session
+- Redirect to the login page if no valid session exists
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Callback URL Mismatch**: Ensure your callback URLs in Auth0 exactly match your site's URL,
+   including the `/oauth/callback` path.
+
+2. **CORS Errors**: Add your site's domain to the Allowed Web Origins in Auth0.
+
+3. **Authentication Loop**: Check that your Auth0 domain includes the protocol (`https://`) but no
+   trailing slash.
+
+4. **Token Validation Errors**: Ensure the audience in your APIToGo configuration matches the
+   identifier of the Auth0 API you created.
+
+## Next Steps
+
+- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
+- Explore other [authentication providers](./authentication.md#authentication-providers) supported
+  by APIToGo
+- Configure [user permissions](./authentication.md#user-data) based on Auth0 roles