# Establish a console mesh session

## Endpoint

```http
POST /session/{name}
```

Mint a holder-bound mesh session offer and per-session caller credential for a managed agent. No request body is parsed. The agent name is percent-decoded. Token authorization precedes method and name checks. An open mesh or a manager without a session establisher returns 503 before name validation. Treat the returned creds as secret.

### Parameters

| Name | Location | Required | Schema |
|---|---|---|---|
| name | path | yes | `{"type":"string","minLength":1}` |

**name:** Percent-encoded managed agent name.


### Responses

#### HTTP 200

Session grant and broker caller connection material.

Content type: `application/json`.

```json
{
  "$ref": "#/components/schemas/SessionEstablishment"
}
```

#### HTTP 400

Missing agent name or malformed percent encoding.

Content type: `text/plain`.

```json
{
  "type": "string"
}
```

#### HTTP 401

The manager console token is missing or invalid.

Content type: `text/plain`.

```json
{
  "type": "string"
}
```

#### HTTP 405

Only POST is accepted.

`Allow`: {"const":"POST"}

Content type: `text/plain`.

```json
{
  "type": "string"
}
```

#### HTTP 429

Session capacity is exhausted; code is resource-exhausted.

Content type: `application/json`.

```json
{
  "$ref": "#/components/schemas/Error"
}
```

#### HTTP 500

Session establishment failed; native refusals include code.

Content type: `application/json`.

```json
{
  "$ref": "#/components/schemas/Error"
}
```

#### HTTP 503

Session establishment is not available on this manager.

Content type: `text/plain`.

```json
{
  "type": "string"
}
```

Authentication and access: Operator HTTP interface of the reference manager console. This is separate from the Dashboard HTTP API. The default bind is 127.0.0.1 on an allocated port; an operator can configure the bind host and port. Every data operation requires the per-manager console token, even on loopback. Supply a bearer header or query parameter t. If both are present, t takes precedence. The launch page keeps its token in the URL fragment.

Read routes also accept other bodyless methods; only the documented GET behavior is promised. Query strings are removed for route dispatch. Session establishment mints credentials for a broker WebSocket connection; the console does not expose a WebSocket terminal endpoint. Static HTML, scripts, styles and favicon resources are outside this API reference.

[OpenAPI specification](https://docs.cotal.ai/manager-console.openapi.json) contains the referenced response schemas. [Complete Markdown reference](/api/manager-console.md).