Redeem a sensor bootstrap token

POST

/v1/sensors/bootstrap

curl --request POST \
  --url https://api.nextpki.com/v1/sensors/bootstrap \
  --header 'Content-Type: application/json' \
  --data '{ "token": "example", "machine_id": "example", "csr": "example", "os": "linux", "arch": "amd64", "version": "0.1.0" }'

Exchanges a single-use bootstrap token for a sensor identity: a signed client certificate, the CA chain and the SPIFFE ID the sensor will present on every later call.

This is the one endpoint that takes no Authorization header. A sensor that is registering has no API token yet; the bootstrap token in the body is the credential. It is worth exactly one successful call - a second attempt is refused with token_already_used.

Rate limit: 1 request per second per source address, burst 5.

Request Body^required

Media typeapplication/json

object

token

required

Single-use bootstrap token, of the form npbst...

string

machine_id

required

Stable identifier of the machine (hostname, OS UUID). Must match the token’s hint if one was set.

string

csr

required

PKCS#10 certificate signing request, either PEM or base64-encoded DER.

string

os

string

Example

linux

arch

string

Example

amd64

version

Sensor version

string

Example

0.1.0

Responses

200

Registered - the certificate is valid for 90 days

Media typeapplication/json

object

certificate

required

Signed client certificate

string

ca_chain

required

Issuing CA

string

spiffe_id

required

string

not_after

required

string format: date-time

ingest_endpoint

required

Where the sensor reports its findings

string

sensor_id

string format: uuid

tenant_id

string format: uuid

Example

{
  "spiffe_id": "spiffe://nextpki.com/tenant/<uuid>/sensor/<machine_id>"
}

400

Malformed body, undecodable CSR, or a machine_id that does not match the hint the token was issued for. The token is not consumed in this case.

Media typeapplication/json

object

error

required

Error class - what a program branches on.

string

Allowed values: invalid_request token_rejected rate_limited bootstrap_unavailable

reason

The specific cause - what a human reads in a terminal.

string

Allowed values: token_unknown token_expired token_already_used csr_not_decodable invalid_input malformed_json empty_body body_too_large

Example

{
  "error": "invalid_request",
  "reason": "token_unknown"
}

403

Token refused. reason names which case it is - token_unknown, token_expired or token_already_used - so an operator at a terminal can tell them apart without asking us.

Media typeapplication/json

object

error

required

Error class - what a program branches on.

string

Allowed values: invalid_request token_rejected rate_limited bootstrap_unavailable

reason

The specific cause - what a human reads in a terminal.

string

Allowed values: token_unknown token_expired token_already_used csr_not_decodable invalid_input malformed_json empty_body body_too_large

Example

{
  "error": "invalid_request",
  "reason": "token_unknown"
}

429

Too many attempts from this address

Media typeapplication/json

object

error

required

Error class - what a program branches on.

string

Allowed values: invalid_request token_rejected rate_limited bootstrap_unavailable

reason

The specific cause - what a human reads in a terminal.

string

Allowed values: token_unknown token_expired token_already_used csr_not_decodable invalid_input malformed_json empty_body body_too_large

Example

{
  "error": "invalid_request",
  "reason": "token_unknown"
}