# Admin GraphQL API

Barycenter exposes an administration API on a dedicated port, separate from the public-facing OIDC endpoints. By default, the admin API listens on the main server port plus one (e.g., if the OIDC server runs on port 8080, the admin API runs on port 8081). This separation allows operators to restrict admin access at the network level using firewalls, Kubernetes NetworkPolicies, or reverse proxy rules without affecting public OIDC traffic.

## Two GraphQL Schemas

The admin API serves two independent GraphQL schemas, each at its own endpoint:

| Endpoint | Playground | Purpose |
|---|---|---|
| `POST /admin/graphql` | `GET /admin/playground` | Entity CRUD operations via [Seaography](./entity-crud.md) |
| `POST /admin/jobs` | `GET /admin/jobs/playground` | [Job management](./job-management.md) and [user 2FA management](./user-2fa.md) |

### Entity CRUD Schema (`/admin/graphql`)

This schema is auto-generated by Seaography from Barycenter's SeaORM entities. It provides full create, read, update, and delete operations for all registered database entities. Use this schema for tasks such as listing users, inspecting sessions, viewing registered clients, or manually managing tokens.

See [Entity CRUD (Seaography)](./entity-crud.md) for details and examples.

### Job and User Management Schema (`/admin/jobs`)

This schema provides custom queries and mutations for operational tasks that go beyond simple CRUD:

- **Trigger background jobs** on demand (e.g., force a cleanup cycle without waiting for the next scheduled run).
- **Query job execution logs** with filtering by job name and failure status.
- **List available jobs** and their schedules.
- **Manage user 2FA settings** (enable/disable 2FA requirements, query enrollment status).

See [Job Management](./job-management.md) and [User 2FA Management](./user-2fa.md) for details.

## Accessing the Admin API

The admin API is intended for operators and automation tooling, not end users. Access it using any GraphQL client, `curl`, or the built-in GraphQL playgrounds.

### Using curl

```bash
# Entity CRUD: list all users
curl -s -X POST http://localhost:8081/admin/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ user { findMany { nodes { id username email } } } }"}'

# Job management: list available jobs
curl -s -X POST http://localhost:8081/admin/jobs \
  -H "Content-Type: application/json" \
  -d '{"query": "{ availableJobs { name description schedule } }"}'
```

### Using the Playground

Open the appropriate playground URL in a browser for interactive query building:

- **Entity CRUD playground**: `http://localhost:8081/admin/playground`
- **Job management playground**: `http://localhost:8081/admin/jobs/playground`

See [GraphQL Playground](./playground.md) for more on using the playground interface.

## Configuration

The admin API port is derived from the main server configuration. If you set the main port via the configuration file or environment variable, the admin port adjusts accordingly:

```toml
[server]
port = 9090
# Admin API will be available on port 9091
```

Or via environment variable:

```bash
export BARYCENTER__SERVER__PORT=9090
# Admin API will be available on port 9091
```

## Security Considerations

The admin API provides unrestricted access to all database entities and operational controls. In production deployments:

- **Do not expose the admin port to the public internet.** Bind it to a loopback or internal network interface, or use firewall rules to restrict access.
- **Use a reverse proxy** with authentication if remote admin access is required.
- **In Kubernetes**, use a separate `Service` for the admin port and restrict access with `NetworkPolicy` resources.

## Further Reading

- [Entity CRUD (Seaography)](./entity-crud.md) -- auto-generated CRUD operations for all entities
- [Job Management](./job-management.md) -- triggering jobs and querying execution logs
- [User 2FA Management](./user-2fa.md) -- managing two-factor authentication requirements
- [GraphQL Playground](./playground.md) -- interactive query building in the browser
