Concorde

Appearance

@shutter-network/concorde/users ​

The HTTP routes this component serves: 2 on the Agent server and 1 on the Public server.

Every path is relative. Each one is printed as the plugin declares it, under whatever prefix the component's constructor registers that plugin at. This page states no mount point, because the constructor is where the mount point is decided.

Generated from what the route plugins in src/users/routes.ts declare, which is what a running Gateway serves at GET /openapi.json. Never edited by hand.

Agent server ​

The Agent server has no authentication of any kind. Everything below is reachable by the agent, and therefore by an injected prompt (ADR-0003). Nothing on it names a credential.

GET / ​

Read Users, newest first

Every User this Gateway has admitted, newest first. These routes are reads. There is no create here: an agent that could mint a User and give it a credential has minted itself an account, so admitting a User is the Operator's own code and has no route. Users cannot be searched or filtered. Attributes are arbitrary JSON that the Gateway cannot index, and a User has no natural key to match on. limit defaults to 50 and is capped at 200. A larger value is refused with a 400 rather than quietly reduced. There is no cursor and no offset, and nothing to narrow by. The Users past the cap are not reachable through this route. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Users.

Query parameters

  • limit integer, optional, 1 to 200, default 50

Responses

200 application/json

The most recently created Users.

  • users array of object, required

    • id string, required

    • attributes any JSON, required

      Arbitrary JSON, defined by the deployment and interpreted by nothing in the Gateway. This is where grouping and therefore authorization live. Nothing on any HTTP surface writes them: a User is admitted from the Operator's own code, and setAttributes has no route anywhere.

    • createdAt string, required

400 application/json

The limit is out of range or not an integer, or a parameter this route does not take was written.

  • statusCode integer, required
  • error string, required
  • message string, required

GET /{id} ​

Read one User by id

One User, by the opaque id whoever admitted them was told. There is no email and no username to find one by. Users cannot be searched or filtered. Attributes are arbitrary JSON that the Gateway cannot index, and a User has no natural key to match on. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Users.

Path parameters

  • id string, required, matching ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Responses

200 application/json

The User.

  • id string, required

  • attributes any JSON, required

    Arbitrary JSON, defined by the deployment and interpreted by nothing in the Gateway. This is where grouping and therefore authorization live. Nothing on any HTTP surface writes them: a User is admitted from the Operator's own code, and setAttributes has no route anywhere.

  • createdAt string, required

400 application/json

The id in the path is not a uuid, or a query parameter was written.

  • statusCode integer, required
  • error string, required
  • message string, required

404 application/json

No User has that id.

  • statusCode integer, required
  • error string, required
  • message string, required

Public server ​

The Public server is what a User's client calls. Which credential each route wants, and which wants none, is in that route's own description below.

GET /me ​

Read the authenticated User

The User this request is acting as, in the same shape the agent's reads answer with. A client resuming after a restart recovers exactly what it was told. The Attributes governing this User's authorization are included. They are not hidden from the User they are about.

It echoes the authenticated User and reads nothing else, so it answers the same way whichever scheme this deployment authenticated the request with. Requires authentication. Present a credential of any scheme this deployment accepts, which is Authorization: Bearer <token> wherever the password login is registered. The User answered with is the one the Gateway authenticated, and no parameter anywhere names another. This route takes no query parameters at all. A credential travels in the body or in the Authorization header, never in a URL. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Users.

Responses

200 application/json

The User the Gateway authenticated.

  • id string, required

  • attributes any JSON, required

    Arbitrary JSON, defined by the deployment and interpreted by nothing in the Gateway. This is where grouping and therefore authorization live. Nothing on any HTTP surface writes them: a User is admitted from the Operator's own code, and setAttributes has no route anywhere.

  • createdAt string, required

400 application/json

A query parameter was written, and this route takes none.

  • statusCode integer, required
  • error string, required
  • message string, required

401 application/json

Authentication failed, which is the whole of what is said: a wrong password, an id nobody holds, a User with no password, and a Token that is missing, malformed, unknown or expired are one status and one message, so nothing here answers who exists.

  • statusCode integer, required
  • error string, required
  • message string, required