API References

The Humanitec API allows you to automate and integrate Humanitec into your developer and operational workflows. The API is a REST based API.

Authentication

Almost all requests made to the Humanitec API require Authentication. Humanitec provides 2 ways of authenticating with the API: API token and session token.

API token authentication

API tokens are used to authenticate requests to the Humanitec API. This form of authentication makes use of a static token. It is intended to be used when machines interact with the Humanitec API. API tokens should be used for very narrow purposes.

They are similar to a password, but are used to interact with the API programmatically rather than interactively.

Generate an API token

To generate an API token, you need to create a service user first. See here for guidance on how to generate API tokens for service users.

Revoke an API token

To revoke an API token, you need to be an admin of the organization. You can revoke a token in the service user settings.

  1. Select the service user that holds the token you would like to revoke.
  2. Choose Revoke.
  3. In the confirmation dialog, choose Revoke API token.

Use an API token

To use an API token, pass the token through the Authorization header.

The following is an example where HUMANITEC_TOKEN is the token you generated and the response lists all active Organizations you have access to:

The CLI picks up the token automatically if it is set as the HUMANITEC_TOKEN environment variable:

humctl get orgs

Pass the token as a request header:

curl -H "Authorization: Bearer ${HUMANITEC_TOKEN}" https://api.humanitec.io/orgs

Session token authentication

This form of authentication makes use of a session token. It is intended to be used when humans interact with the Humanitec API. Session tokens expire after a period of time.

This means that a new session token will need to be generated regularly. This makes them well suited to working in short sessions, but not for automation.

There is no tooling support yet to easily generate session tokens. If needed, you can extract one from your browser’s requests when working with the Platform Orchestrator UI after authenticating . Look for the token cookie and use its value.

The token is passed to the API via the Authorization header. Assuming the issued token is HUMANITEC_SESSION, the same request can be made as follows:

Pass the token to the CLI as a parameter when it is not using the default HUMANITEC_ORG environment variable:

humctl get orgs --token $HUMANITEC_SESSION

Pass the token as a request header:

curl -H "Authorization: Bearer ${HUMANITEC_SESSION}" https://api.humanitec.io/orgs

Content Types

All of the Humanitec API unless explicitly only accepts content types of application/json and will always return valid application/json or an empty response.

CLI References