API (beta)

The API is currently in beta. We are looking for feedback on both, the API design itself as well as the documentation.

The Humanitec API allows for automating and integrating of Humanitec into your workflows

The API is a REST based API. It is based around a set of objects:

Authentication

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

Bearer Authentication

This form of authentication makes use of a static token. It is intended to be used when machines interact with the Humanitec API. Bearer tokens should be used for very narrow purposes. This allows for the token to be revoked if it is compromised and so limit the scope of exposure.

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

curl -H 'Authorization: Bearer HUMANITEC_TOKEN' https://api.humanitec.io/orgs/my-org/apps

JWT Authentication

This form of authentication makes use of a JSON Web Token (JWT). It is intended to be used when humans interact with the Humanitec API. JWTs expire after a period of time. This means that a new JWT will need to be generated regularly. This makes them well suited to working in short sessions, but not for automation. (See [Bearer Authentication].)

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

curl -H 'Authorization: JWT HUMANITEC_JWT' https://api.humanitec.io/orgs/my-org/apps

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.

Response Codes

Success

Any response code in the 2xx range should be regarded as success.

Code Meaning
200 Success
201 Success (In future, 201 will be replaced by 200)
204 Success, but no content in response

Note: We plan to simplify the interface by replacing 201 with 200 status codes.

Failure

Any response code in the 4xx should be regarded as an error which can be rectified by the client. 5xx error codes indicate errors that cannot be corrected by the client.

Code Meaning
400 General error. (Body will contain details)
401 Attempt to access protected resource without Authorization Header.
403 The Bearer or JWT does not grant access to the requested resource.
404 Resource not found.
405 Method not allowed
409 Conflict. Usually indicated a resource with that ID already exists.
422 Unprocessable Entity. The body was not valid JSON, was empty or contained an object different from what was expected.
429 Too many requests - request rate limit has been reached.
500 Internal Error. If it occurs repeatedly, contact support.