HTTP API

Conch provides a HTTP API to perform signing requests.

GET /sign

Sign a public SSH key, using the provided JWT to authorise.

Example request:

GET /sign?public_key=ssh-ed25519%20AAAAC3NzaC1lZ<example-snipped> HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cC<example snipped>

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>",
  "platforms": {
    "batch.cluster1.example": {
      "alias": "cluster1.example",
      "hostname": "1.access.example.com",
      "proxy_jump": "bastion.example.com"
    },
    "batch.cluster2.example": {
      "alias": "cluster2.example",
      "hostname": "2.access.example.com",
      "proxy_jump": "bastion.example.com"
    }
  },
  "projects": {
    "project-a": [
      "batch.cluster1.example",
    ],
    "project-b": [
      "batch.cluster2.example"
    ]
  },
  "short_name": "test_person",
  "user": "test@example.com",
  "version": 2
}
Query Parameters:
  • public_key (string) – the SSH public key to sign

Request Headers:
Response JSON Object:
  • certificate (string) – the SSH certificate

  • platforms (Platforms) – the platforms the certificate can be used on. See platforms for the structure.

  • projects (Project) – the projects the user is part of. This is extracted from the projects claim.

  • short_name (string) – the short name of the user

  • user (string) – the email address of the user

  • version (integer) – the version of the response. Currently 2.

GET /issuer

Deprecated since version 0.3: Use GET /oidc instead.

Get the URL of the OIDC issuer.

Example request:

GET /issuer HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK

https://keycloak.example.com/realms/example
GET /oidc

Added in version 0.3.

Get the details of the OIDC issuer and client information to use.

Example request:

GET /client_id HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "issuer": "https://keycloak.example.com/realms/example",
  "client_id": "clifton",
  "version": 1
}
Response JSON Object:
  • issuer (string) – the URL of the OIDC issuer.

  • client_id (string) – the ID of the OIDC client to use when talking to the issuer.

  • version (integer) – the version of the response. Currently 1.

GET /public_key

Added in version 0.2.

Get the public part of the currently used signing key.

Example request:

GET /public_key HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBsaKBqZPg<example snipped>
GET /health

Added in version 0.1.3.

Check the health of the service.

Example request:

GET /health HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{}
Status Codes:
  • 200 OK – Conch is running and working.