# /api/v1/hydra/clients (management)

Source-derived management endpoint contract, authentication, request validation, responses, and errors.

Source: https://docs.minds.sh/docs/api/platform/reference/management--api-v1-hydra-clients



This is the **management** service route. Its origin and authentication are described in [Platform API overview](/docs/api/platform) and [Authentication](/docs/api/platform/authentication). A path shared by another service is a different endpoint.

| Property                       | Contract                                                                       |
| ------------------------------ | ------------------------------------------------------------------------------ |
| Methods                        | POST, GET                                                                      |
| Path                           | `/api/v1/hydra/clients`                                                        |
| Path parameters                | None                                                                           |
| Query parameters read in route | None read directly; schema validation below may define additional fields       |
| Headers read in route          | No additional direct header reads; authentication helpers may read credentials |

## Authentication and access [#authentication-and-access]

Endpoint-specific authentication in the source excerpt below; do not infer support for a dashboard API key.

## Method behavior [#method-behavior]

The handler excerpt preserves field validation, response envelopes, cookie changes, and exception branches. Values returned by service helpers retain their named response type above; for passthrough routes, the upstream response is authoritative.

### POST [#post]

```typescript
export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const { clientId, clientSecret, redirectUri } = body;

    if (!clientId || !clientSecret || !redirectUri) {
      return NextResponse.json(
        { error: 'Missing required fields: clientId, clientSecret, redirectUri' },
        { status: 400 }
      );
    }

    // Create Hydra client via Kong-routed admin API
    const adminGatewayUrl = env.KONG_GATEWAY_URL ?? 'https://api.l1fe.ai'
    const response = await fetch(`${adminGatewayUrl}/admin/hydra/clients`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': env.HYDRA_SYSTEM_SECRET || '',
      },
      body: JSON.stringify({
        client_id: clientId,
        client_secret: clientSecret,
        grant_types: ['authorization_code', 'refresh_token'],
        response_types: ['code'],
        scope: 'openid profile email tenant:access',
        redirect_uris: [redirectUri],
      }),
    });

    if (!response.ok) {
      const errorText = await response.text();
      console.error('Hydra API error:', response.status, errorText);
      return NextResponse.json(
        { error: `Hydra API error: ${response.statusText}` },
        { status: response.status }
      );
    }

    const client = await response.json();
    return NextResponse.json(client);
  } catch (error) {
    console.error('Error creating Hydra client:', error);
    return NextResponse.json(
      { error: 'Failed to create client' },
      { status: 500 }
    );
  }
}
```

Source: `minds-ui/apps/api-service/app/api/v1/hydra/clients/route.ts:4`.

### GET [#get]

```typescript
export async function GET(request: NextRequest) {
  try {
    // List existing Hydra clients
    const adminGatewayUrl = env.KONG_GATEWAY_URL ?? 'https://api.l1fe.ai'
    const response = await fetch(`${adminGatewayUrl}/admin/hydra/clients`, {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': env.HYDRA_SYSTEM_SECRET || '',
      },
    });

    if (!response.ok) {
      const errorText = await response.text();
      console.error('Hydra API error:', response.status, errorText);
      return NextResponse.json(
        { error: `Hydra API error: ${response.statusText}` },
        { status: response.status }
      );
    }

    const clients = await response.json();
    return NextResponse.json(clients);
  } catch (error) {
    console.error('Error listing Hydra clients:', error);
    return NextResponse.json(
      { error: 'Failed to list clients' },
      { status: 500 }
    );
  }
}
```

Source: `minds-ui/apps/api-service/app/api/v1/hydra/clients/route.ts:54`.

## Response and error branches [#response-and-error-branches]

Literal HTTP statuses in the route: 400, 500. Shared management error classes are defined in [Errors and responses](/docs/api/platform/errors).

```typescript
request.json()
```

Source: `minds-ui/apps/api-service/app/api/v1/hydra/clients/route.ts:6`.

```typescript
NextResponse.json(
        { error: 'Missing required fields: clientId, clientSecret, redirectUri' },
        { status: 400 }
      )
```

Source: `minds-ui/apps/api-service/app/api/v1/hydra/clients/route.ts:10`.

```typescript
NextResponse.json(
        { error: `Hydra API error: ${response.statusText}` },
        { status: response.status }
      )
```

Source: `minds-ui/apps/api-service/app/api/v1/hydra/clients/route.ts:37`.

```typescript
response.json()
```

Source: `minds-ui/apps/api-service/app/api/v1/hydra/clients/route.ts:43`.

```typescript
NextResponse.json(client)
```

Source: `minds-ui/apps/api-service/app/api/v1/hydra/clients/route.ts:44`.

```typescript
NextResponse.json(
      { error: 'Failed to create client' },
      { status: 500 }
    )
```

Source: `minds-ui/apps/api-service/app/api/v1/hydra/clients/route.ts:47`.

```typescript
NextResponse.json(
        { error: `Hydra API error: ${response.statusText}` },
        { status: response.status }
      )
```

Source: `minds-ui/apps/api-service/app/api/v1/hydra/clients/route.ts:69`.

```typescript
response.json()
```

Source: `minds-ui/apps/api-service/app/api/v1/hydra/clients/route.ts:75`.

```typescript
NextResponse.json(clients)
```

Source: `minds-ui/apps/api-service/app/api/v1/hydra/clients/route.ts:76`.

```typescript
NextResponse.json(
      { error: 'Failed to list clients' },
      { status: 500 }
    )
```

Source: `minds-ui/apps/api-service/app/api/v1/hydra/clients/route.ts:79`.

## Service dependencies [#service-dependencies]

* `minds-ui/apps/api-service/env.ts`

## Evidence [#evidence]

Generated from the local source snapshot on 2026-09-12. This page documents implemented code and does not certify a deployed service, permissions configuration, or successful provider operation.

Source file: `minds-ui/apps/api-service/app/api/v1/hydra/clients/route.ts`. SHA-256: `e0486b430f1f89d6a6534f49ad160f3445d105acc9fc138660fea0318f2c5ea5`.