From 9da8c2f54a825ce64653fddf415e445d0a63b1e9 Mon Sep 17 00:00:00 2001 From: Brandon Hopkins Date: Mon, 5 Jan 2026 22:55:04 -0800 Subject: [PATCH] Remove API Reference --- src/components/NavigationDocs.jsx | 1 - .../identity-providers/api-reference.mdx | 490 ------------------ .../identity-providers/authentik.mdx | 2 +- .../selfhosted/identity-providers/index.mdx | 2 +- .../identity-providers/keycloak.mdx | 2 +- .../identity-providers/pocketid.mdx | 2 +- 6 files changed, 4 insertions(+), 495 deletions(-) delete mode 100644 src/pages/selfhosted/identity-providers/api-reference.mdx diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 39a2233b..59ca480e 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -288,7 +288,6 @@ export const docsNavigation = [ isOpen: false, links: [ { title: 'Using IdPs on Self-Hosted', href: '/selfhosted/identity-providers' }, - { title: 'API Reference', href: '/selfhosted/identity-providers/api-reference' }, { title: 'Self-hosted IdPs', isOpen: true, diff --git a/src/pages/selfhosted/identity-providers/api-reference.mdx b/src/pages/selfhosted/identity-providers/api-reference.mdx deleted file mode 100644 index e73fa247..00000000 --- a/src/pages/selfhosted/identity-providers/api-reference.mdx +++ /dev/null @@ -1,490 +0,0 @@ -# Identity Provider API Reference - -This page documents the API endpoints for managing identity providers when using the [embedded IdP](/selfhosted/identity-providers#local-user-management). - -## Base URL - -All endpoints are relative to your NetBird Management API: - -``` -https://netbird.example.com/api -``` - -## Authentication - -Most endpoints require authentication via Bearer token: - -``` -Authorization: Bearer -``` - -## Permissions - -Identity provider management requires administrator privileges. The following permission is required: - -- `identity_providers` permission - For managing identity provider configurations -- `settings:read` - For viewing the Identity Providers tab - ---- - -## Instance Setup - -These endpoints handle the initial setup when embedded IdP is enabled and no accounts exist. Both endpoints are **unauthenticated** and only work before setup is complete. - -### Get Instance Status - -Check if the instance requires initial setup. - -```http -GET /instance -``` - -**Authentication:** None required (public endpoint) - -**Response:** - -```json -{ - "setup_required": true -} -``` - -| Field | Type | Description | -|-------|------|-------------| -| `setup_required` | boolean | `true` if no accounts exist and setup is needed | - -### Complete Setup - -Create the initial owner account. - -```http -POST /instance/setup -``` - -**Authentication:** None required (only available during setup) - -**Request Body:** - -```json -{ - "email": "admin@example.com", - "password": "securepassword123", - "name": "Admin User" -} -``` - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `email` | string | Yes | Email address for the owner account | -| `password` | string | Yes | Password (minimum 8 characters) | -| `name` | string | No | Display name | - -**Response:** - -```json -{ - "user_id": "user-abc123", - "account_id": "account-xyz789" -} -``` - -**Errors:** - -| Status | Code | Description | -|--------|------|-------------| -| 400 | `invalid_request` | Missing required fields or invalid format | -| 412 | `precondition_failed` | Setup already completed (redirects to login) | -| 503 | `idp_unavailable` | Embedded IdP is not enabled | - ---- - -## Identity Providers (Connectors) - -Manage external identity provider connectors. The Identity Providers tab is visible in Settings when `embedded_idp_enabled` is `true` in account settings. - -### List Identity Providers - -Get all configured identity providers. - -```http -GET /identity-providers -``` - -**Response:** - -```json -[ - { - "id": "idp-abc123", - "type": "google", - "name": "Google Workspace", - "client_id": "123456789.apps.googleusercontent.com", - "issuer": "", - "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123" - }, - { - "id": "idp-def456", - "type": "oidc", - "name": "Corporate SSO", - "client_id": "netbird-client", - "issuer": "https://sso.example.com", - "redirect_url": "https://netbird.example.com/api/idp/callback/idp-def456" - } -] -``` - - -Client secrets are never returned in API responses for security. - - -### Get Identity Provider - -Get details for a specific identity provider. - -```http -GET /identity-providers/{id} -``` - -**Path Parameters:** - -| Parameter | Type | Description | -|-----------|------|-------------| -| `id` | string | Identity provider ID | - -**Response:** - -```json -{ - "id": "idp-abc123", - "type": "google", - "name": "Google Workspace", - "client_id": "123456789.apps.googleusercontent.com", - "issuer": "", - "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123" -} -``` - -### Create Identity Provider - -Add a new identity provider connector. - -```http -POST /identity-providers -``` - -**Request Body:** - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | Yes | Provider type (see below) | -| `name` | string | Yes | Display name on login page | -| `client_id` | string | Yes | OAuth client ID | -| `client_secret` | string | Yes | OAuth client secret | -| `issuer` | string | Conditional | Issuer URL (required for oidc, okta, zitadel, pocketid) | - -**Provider Types:** - -| Type | Description | Requires Issuer | -|------|-------------|-----------------| -| `google` | Google accounts / Google Workspace | No | -| `microsoft` | Microsoft personal accounts | No | -| `entra` | Microsoft Entra ID (Azure AD) | No | -| `okta` | Okta SSO | Yes | -| `zitadel` | Zitadel IdP | Yes | -| `pocketid` | PocketID | Yes | -| `oidc` | Generic OIDC provider | Yes | - -#### Google Configuration - -```json -{ - "type": "google", - "name": "Google Workspace", - "client_id": "123456789.apps.googleusercontent.com", - "client_secret": "GOCSPX-xxxxx" -} -``` - - -Google and Microsoft types do not require an `issuer` field - the issuer is determined automatically. - - -#### Microsoft / Entra ID Configuration - -```json -{ - "type": "entra", - "name": "Microsoft Entra ID", - "client_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", - "client_secret": "xxxxx" -} -``` - -Use `microsoft` for personal Microsoft accounts, or `entra` for Azure AD / work accounts. - -#### Okta Configuration - -```json -{ - "type": "okta", - "name": "Okta SSO", - "client_id": "0oaxxxxxxxxxx", - "client_secret": "xxxxx", - "issuer": "https://yourcompany.okta.com/oauth2/default" -} -``` - -#### Zitadel Configuration - -```json -{ - "type": "zitadel", - "name": "Zitadel", - "client_id": "123456789", - "client_secret": "xxxxx", - "issuer": "https://zitadel.example.com" -} -``` - -#### PocketID Configuration - -```json -{ - "type": "pocketid", - "name": "PocketID", - "client_id": "netbird", - "client_secret": "xxxxx", - "issuer": "https://pocketid.example.com" -} -``` - -#### Generic OIDC Configuration - -```json -{ - "type": "oidc", - "name": "Custom SSO", - "client_id": "netbird-client", - "client_secret": "xxxxx", - "issuer": "https://sso.example.com" -} -``` - -The issuer URL must have a valid `/.well-known/openid-configuration` endpoint. - -**Response:** - -On successful creation, the response includes a `redirect_url` that must be configured in your identity provider: - -```json -{ - "id": "idp-abc123", - "type": "google", - "name": "Google Workspace", - "client_id": "123456789.apps.googleusercontent.com", - "issuer": "", - "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123" -} -``` - - -**Important:** After creating an identity provider, you must configure the `redirect_url` in your IdP's OAuth application settings. The Dashboard shows a modal with copy functionality after successful creation. - - -**Errors:** - -| Status | Code | Description | -|--------|------|-------------| -| 400 | `invalid_request` | Missing required fields | -| 400 | `invalid_type` | Unknown provider type | -| 403 | `permission_denied` | Insufficient permissions | - -### Update Identity Provider - -Update an existing identity provider. - -```http -PUT /identity-providers/{id} -``` - -**Path Parameters:** - -| Parameter | Type | Description | -|-----------|------|-------------| -| `id` | string | Identity provider ID | - -**Request Body:** - -Include only fields you want to update. The `type` cannot be changed. - -```json -{ - "name": "Updated Name", - "client_id": "new-client-id", - "client_secret": "new-secret" -} -``` - - -If `client_secret` is empty or omitted, the existing secret is preserved. The help text in the Dashboard says: "Leave empty to keep the existing secret." - - -**Response:** - -```json -{ - "id": "idp-abc123", - "type": "google", - "name": "Updated Name", - "client_id": "new-client-id", - "issuer": "", - "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123" -} -``` - -### Delete Identity Provider - -Remove an identity provider connector. - -```http -DELETE /identity-providers/{id} -``` - -**Path Parameters:** - -| Parameter | Type | Description | -|-----------|------|-------------| -| `id` | string | Identity provider ID | - -**Response:** - -``` -204 No Content -``` - -**Errors:** - -| Status | Code | Description | -|--------|------|-------------| -| 404 | `not_found` | Identity provider not found | -| 403 | `permission_denied` | Insufficient permissions | - - -Deleting an identity provider will prevent users who authenticate exclusively through that provider from logging in. - - ---- - -## Users (Embedded IdP) - -When embedded IdP is enabled, the Dashboard shows a **"Create User"** button instead of "Invite User". Created users receive a generated password that is shown only once. - -### Create User - -Create a new local user. In the Dashboard, after creation, a modal displays the generated password with a copy button and the warning: *"This password will only be shown once. Please copy it now."* - -```http -POST /users -``` - -**Request Body:** - -```json -{ - "email": "user@example.com", - "name": "New User", - "role": "user", - "auto_groups": ["group-id-1", "group-id-2"] -} -``` - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `email` | string | Yes | User's email address | -| `name` | string | Yes | Display name | -| `role` | string | No | Role: `admin`, `user` (default: `user`) | -| `auto_groups` | string[] | No | Groups to automatically assign | - -**Response:** - -```json -{ - "id": "user-abc123", - "email": "user@example.com", - "name": "New User", - "role": "user", - "status": "active", - "password": "generated-password-here" -} -``` - - -The `password` field is only included in the response when creating a user with embedded IdP enabled. It is never returned in subsequent API calls. Store it securely or share it with the user immediately. - - -### User IdP Association - -When users authenticate through an external identity provider connector, their user record includes an `idp_id` field linking them to the provider. The Dashboard displays an IdP badge (with the provider's icon) next to the user's name in the Users table. - -```json -{ - "id": "user-abc123", - "email": "user@example.com", - "name": "User Name", - "role": "user", - "status": "active", - "idp_id": "idp-def456" -} -``` - - -This endpoint is only available when embedded IdP is enabled (`account.settings.extra.embedded_idp_enabled: true`). With external IdPs, users are provisioned through the IdP. - - ---- - -## Error Responses - -All error responses follow this format: - -```json -{ - "error": { - "code": "error_code", - "message": "Human-readable error message", - "details": {} - } -} -``` - -### Common Error Codes - -| Code | HTTP Status | Description | -|------|-------------|-------------| -| `invalid_request` | 400 | Request body is malformed or missing required fields | -| `invalid_config` | 400 | Provider configuration is invalid | -| `unauthorized` | 401 | Missing or invalid authentication token | -| `permission_denied` | 403 | Insufficient permissions for this operation | -| `not_found` | 404 | Requested resource not found | -| `duplicate` | 409 | Resource already exists | -| `idp_unavailable` | 503 | Embedded IdP is not enabled or unavailable | - ---- - -## Rate Limits - -API requests are subject to rate limiting: - -| Endpoint Category | Rate Limit | -|-------------------|------------| -| Read operations | 100 requests/minute | -| Write operations | 20 requests/minute | -| Onboarding | 5 requests/minute | - -Rate limit headers are included in responses: - -``` -X-RateLimit-Limit: 100 -X-RateLimit-Remaining: 95 -X-RateLimit-Reset: 1642089600 -``` \ No newline at end of file diff --git a/src/pages/selfhosted/identity-providers/authentik.mdx b/src/pages/selfhosted/identity-providers/authentik.mdx index b5e37011..184f42a3 100644 --- a/src/pages/selfhosted/identity-providers/authentik.mdx +++ b/src/pages/selfhosted/identity-providers/authentik.mdx @@ -239,4 +239,4 @@ You've configured all required resources in Authentik. Continue with the [NetBir - [Authentik Documentation](https://goauthentik.io/docs/) - [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management) -- [API Reference](/selfhosted/identity-providers/api-reference) \ No newline at end of file +- [API Reference](/api/resources/identity-providers) \ No newline at end of file diff --git a/src/pages/selfhosted/identity-providers/index.mdx b/src/pages/selfhosted/identity-providers/index.mdx index 7618197c..b446fa78 100644 --- a/src/pages/selfhosted/identity-providers/index.mdx +++ b/src/pages/selfhosted/identity-providers/index.mdx @@ -470,7 +470,7 @@ curl -X POST "https://netbird.example.com/api/identity-providers" \ }' ``` -See the [API Reference](/selfhosted/identity-providers/api-reference) for complete documentation. +See the [API Reference](/api/resources/identity-providers) for complete documentation. For instance setup endpoints, see [Accounts API](/api/resources/accounts). For user creation with embedded IdP, see [Users API](/api/resources/users). ### Managing Connectors via API diff --git a/src/pages/selfhosted/identity-providers/keycloak.mdx b/src/pages/selfhosted/identity-providers/keycloak.mdx index 33a3b3da..19130474 100644 --- a/src/pages/selfhosted/identity-providers/keycloak.mdx +++ b/src/pages/selfhosted/identity-providers/keycloak.mdx @@ -321,4 +321,4 @@ You've configured all required resources in Keycloak. Continue with the [NetBird - [Keycloak Documentation](https://www.keycloak.org/documentation) - [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management) -- [API Reference](/selfhosted/identity-providers/api-reference) \ No newline at end of file +- [API Reference](/api/resources/identity-providers) \ No newline at end of file diff --git a/src/pages/selfhosted/identity-providers/pocketid.mdx b/src/pages/selfhosted/identity-providers/pocketid.mdx index b9fb805a..0f1e5f06 100644 --- a/src/pages/selfhosted/identity-providers/pocketid.mdx +++ b/src/pages/selfhosted/identity-providers/pocketid.mdx @@ -179,4 +179,4 @@ You've configured all required resources in PocketID. Continue with the [NetBird - [PocketID Documentation](https://pocket-id.org/docs) - [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management) -- [API Reference](/selfhosted/identity-providers/api-reference) \ No newline at end of file +- [API Reference](/api/resources/identity-providers) \ No newline at end of file