Forming orchestrator API requests

Authenticating to the orchestrator API with a token

You need to authenticate requests to the orchestrators’s API. You can do this using user authentication tokens.

For detailed information about authentication tokens, see Token-based authentication. The following example shows how to use a token in an API request.

To use the jobs endpoint of the orchestrator API to get a list of all jobs that exist in the orchestrator, along with their associated metadata, you'd first generate a token with the puppet-access tool. You'd then copy that token and replace <TOKEN> with that string in the following request:

auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/jobs"

curl --insecure --header "$auth_header" "$uri"Copied!

See Usage notes for curl examples for information about forming curl commands.

Example token usage: deploy an environment

If you want to deploy an environment with the orchestrator's API, you can form a request with the token you generated earlier. For example:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/command/deploy"
data='{"environment": "production", "scope" : { "node_group" : "00000000-0000-4000-8000-000000000000" }}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"Copied!

This returns a JSON structure that includes a link to the new job started by the orchestrator.

{
  "job" : {
    "id" : "https://orchestrator.vm:8143/orchestrator/v1/jobs/81",
    "name" : "81"
  }
}Copied!

You can make an additional request to get more information about the job. For example:

auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/jobs/81"

curl --insecure --header "$auth_header" "$uri"Copied!