Create a host

Creates a host using the Host Factory and returns a JSON description of it. If the host already exists, the API key of that host is rotated.

Requires a Host Factory token which can be created using the Create Tokens API. In practice, this token is usually provided automatically as part of Conjur integration with your host provisioning infrastructure.

If the Host Factory token was created with a CIDR restriction, you must make this API request from a allowlisted address.

URI

  
POST /host_factories/hosts

Example with curl and jq

Supposing that you have a Host Factory token and want to create a new host called “brand-new-host”:

  
token="1bcarsc2bqvsxt6cnd74xem8yf15gtma71vp23y315n0z201c1jza7"

curl --request POST --data-urlencode id=brand-new-host \
     --header "Authorization: Token token=\"$token\"" \
     https://eval.conjur.org/host_factories/hosts \
     | jq .

Request Headers

A Host Factory token must be provided as part of an HTTP Authorization header. For example:

Authorization: Token token=2c0vfj61pmah3efbgpcz2x9vzcy1ycskfkyqy0kgk1fv014880f4

Request Body Parameters

Parameter

Type

Mandatory

Description

id

String

Yes

Identifier of the host to be created. It will be created within the account of the Host Factory.

Example: brand-new-host

annotations

Object

No

Annotations to apply to the new host

Example: annotation[puppet]=true&annotation[description]=new+db+host

Response

Code

Description

201

A host was created, its definition is returned as a JSON document in the response body

401

The token was invalid, expired, or the CIDR restriction was not satisfied

422

The request body was empty or a parameter was not formatted correctly

Example URI

  
POST /host_factories/hosts

Response 201

Headers

  
Content-Type: application/json

Body

  
{
  "created_at": "2017-08-07T22:30:00.145+00:00",
  "id": "myorg:host:brand-new-host",
  "owner": "myorg:host_factory:hf-db",
  "permissions": [],
  "annotations": [],
  "api_key": "rq5bk73nwjnm52zdj87993ezmvx3m75k3whwxszekvmnwdqek0r"
}