# @flink-app/management-api-plugin

> Flink plugin that makes it possible to expose management api:s for other plugins

Latest version **1.0.0** (published 2026-02-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @flink-app/management-api-plugin
pnpm add @flink-app/management-api-plugin
yarn add @flink-app/management-api-plugin
bun add @flink-app/management-api-plugin
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2026-02-01 |
| First published | 2021-07-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 98.3 KB |
| Known vulnerabilities | 0 (+3 in 1 direct dependencies) |
| Install scripts | no |
| Author | johan@frost.se |
| Maintainers | joelso, jenkins-frost, johanfrost |

## Links

- npm: https://www.npmjs.com/package/@flink-app/management-api-plugin
- npm.io page: https://npm.io/package/@flink-app/management-api-plugin

## Dependencies (3)

- [bcrypt](https://npm.io/package/bcrypt.md) ^5.0.1
- [jsonwebtoken](https://npm.io/package/jsonwebtoken.md) ^8.5.1
- [@flink-app/flink](https://npm.io/package/@flink-app/flink.md) 1.0.0

## Recent versions

- 1.0.0 (latest) — 2026-02-01
- 2.0.0-alpha.131 (alpha) — 2026-10-28
- 2.0.0-alpha.130 — 2026-10-25
- 2.0.0-alpha.129 — 2026-10-25
- 2.0.0-alpha.128 — 2026-10-22
- 2.0.0-alpha.127 — 2026-10-18
- 2.0.0-alpha.126 — 2026-10-18
- 2.0.0-alpha.125 — 2026-10-17
- 2.0.0-alpha.124 — 2026-10-16
- 2.0.0-alpha.123 — 2026-09-30
- 2.0.0-alpha.122 — 2026-09-28
- 2.0.0-alpha.121 — 2026-09-19
- 2.0.0-alpha.120 — 2026-09-18
- 2.0.0-alpha.119 — 2026-09-13
- 2.0.0-alpha.118 — 2026-09-11
- … 149 more at https://npm.io/package/@flink-app/management-api-plugin/versions

## README

# @flink-app/management-api-plugin

A Flink plugin that provides a secure management API system with built-in user authentication and module registration. This plugin enables other plugins to expose their own management endpoints through a centralized API.

## Features

- Built-in user management system with authentication
- JWT-based token authentication
- Module-based architecture for extensibility
- Token or JWT authentication for all endpoints
- Automatic endpoint registration for modules
- MongoDB-backed user storage
- Password hashing with bcrypt

## Installation

```bash
npm install @flink-app/management-api-plugin
```

## Usage

### Basic Setup

```typescript
import { FlinkApp } from "@flink-app/flink";
import { managementApiPlugin } from "@flink-app/management-api-plugin";

function start() {
  new FlinkApp<AppContext>({
    name: "My app",
    plugins: [
      managementApiPlugin({
        token: "SECRET_TOKEN_USED_TO_COMMUNICATE_WITH_THE_API",
        jwtSecret: "JWT_SECRET_USED_TO_GENERATE_LOGGED_IN_TOKENS",
        modules: [],
        baseUrl: "/managementapi", // optional, defaults to /managementapi
      }),
    ],
  }).start();
}
```

## Configuration Options

- `token` (required): Master token for initial authentication and user creation
- `jwtSecret` (required): Secret key for JWT token generation and verification
- `modules` (required): Array of management API modules to register
- `baseUrl` (optional): Base URL for all management API endpoints (defaults to `/managementapi`)

## Authentication

The management API supports two authentication methods:

1. **Master Token**: Use the `token` specified during plugin initialization
2. **JWT Token**: Login with a management user to receive a JWT token

All requests (except login) must include one of these tokens in the `management-token` header.

## Built-in User Management

The plugin includes a complete user management system:

### Endpoints

- `POST /managementapi/managementapiuser` - Create new user
- `POST /managementapi/managementapiuser/login` - Login and receive JWT token
- `GET /managementapi/managementapiuser` - List all users
- `GET /managementapi/managementapiuser/me` - Get current user info
- `GET /managementapi/managementapiuser/:userid` - Get user by ID
- `PUT /managementapi/managementapiuser/:userid` - Update user
- `DELETE /managementapi/managementapiuser/:userid` - Delete user

### Creating Your First User

To create the initial management user, make a POST request with the master token:

```bash
curl 'https://YOUR-API-URL/managementapi/managementapiuser' \
  -H 'management-token: SECRET_TOKEN_USED_TO_COMMUNICATE_WITH_THE_API' \
  -H 'Content-Type: application/json' \
  --data-raw '{"username":"admin","password":"secure_password"}'
```

### Logging In

```bash
curl 'https://YOUR-API-URL/managementapi/managementapiuser/login' \
  -H 'Content-Type: application/json' \
  --data-raw '{"username":"admin","password":"secure_password"}'
```

This returns a JWT token that can be used in the `management-token` header for subsequent requests.

## Creating Management Modules

Other plugins can create management modules that get registered with this plugin:

```typescript
import { ManagementApiModule, ManagementApiType } from "@flink-app/management-api-plugin";
import { HttpMethod } from "@flink-app/flink";

const myModule: ManagementApiModule = {
  id: "my-module",
  type: ManagementApiType.custom, // or other types
  ui: true,
  uiSettings: {
    title: "My Module",
    icon: "",
    features: [],
  },
  endpoints: [
    {
      handler: myHandler,
      routeProps: {
        method: HttpMethod.get,
        path: "/list",
        docs: "List all items",
      },
    },
  ],
  data: {},
};

// Register with management API plugin
managementApiPlugin({
  token: "...",
  jwtSecret: "...",
  modules: [myModule],
});
```

## Module Types

The plugin supports different module types via `ManagementApiType`:

- `managementUser` - User management (built-in)
- `action` - Action modules (used by management-actions-plugin)
- Custom types can be defined

## API Endpoints

### Get Management API Info

```
GET /managementapi
```

Returns information about all registered modules and their configuration.

## TypeScript Support

The plugin includes full TypeScript definitions. To use the plugin context in your application:

```typescript
import { managementApiPluginContext } from "@flink-app/management-api-plugin";

interface MyContext extends FlinkContext<managementApiPluginContext> {
  // your context
}
```

## Database Requirements

This plugin requires MongoDB to be configured in your Flink app for user management. The plugin automatically creates a `ManagementUserRepo` repository.

## Security Notes

- Always use strong, unique values for `token` and `jwtSecret`
- Store secrets in environment variables, never commit them to source control
- The master token provides full access - protect it carefully
- User passwords are automatically hashed using bcrypt
- The login endpoint is the only endpoint that doesn't require authentication

## Example Integration with Management Actions Plugin

```typescript
import { managementApiPlugin } from "@flink-app/management-api-plugin";
import { GetManagementModule } from "@flink-app/management-actions-plugin";

const actionsModule = GetManagementModule({
  ui: true,
  uiSettings: { title: "Actions" },
  actions: [
    // your actions
  ],
});

new FlinkApp<AppContext>({
  plugins: [
    managementApiPlugin({
      token: process.env.MANAGEMENT_TOKEN!,
      jwtSecret: process.env.JWT_SECRET!,
      modules: [actionsModule],
    }),
  ],
}).start();
```

## License

MIT

---
_Source: https://npm.io/package/@flink-app/management-api-plugin · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._