Skip to main content

The Akuity API

The Akuity API allows you to manage the Akuity Platform resources using the REST API.

Getting an API Key​

In order to use the API you will first need to create an API key. Copy the following values from your API key:

  • AKUITY_API_KEY_ID
  • AKUITY_API_KEY_SECRET.

Accessing the API​

note

The API Server address is https://akuity.cloud/api/v1/

You can browse the current API Reference.

You can connect from your local workstation, with any tool that speaks HTTP (such as postman, httpie, curl, wget etc.).

Authentication​

The API allows you to authenticate via HTTP basic auth using the Authorization Header, or with a bearer credential obtained by a service account.

Basic Auth​

Basic auth has been around for a long time, and is pretty simple. You will pass in a http header that looks like this.

Authorization: Basic <credentials>

where credentials is the Base64 encoding of AKUITY_API_KEY_ID and AKUITY_API_KEY_SECRET joined by a single colon :

export AKUITY_API_KEY_ID=mySecretKeyId
export AKUITY_API_KEY_SECRET=blahblahSecretValueBlahblah
export API_CRED=`echo -n $AKUITY_API_KEY_ID:$AKUITY_API_KEY_SECRET | base64`
echo -n $API_CRED
> bXlTZWNyZXRLZXlJZDpibGFoYmxhaFNlY3JldFZhbHVlQmxhaGJsYWg=
note

In zsh, a % symbol is placed at the end of a line where zsh inserted a newline for us.

It is important to include echo’s -n option when piping content to an encoder to avoid a newline character being included in the encoded output.

If the credentials are not working, check to make sure your base64 encoded value is correct

echo -n "$AKUITY_API_KEY_ID:$AKUITY_API_KEY_SECRET" | base64 | base64 -d

Bearer credential​

A service account exchanges an OIDC token for a short-lived credential at POST /api/v1/organizations/<organization ID>/oauth/token. Send that credential as a bearer token:

Authorization: Bearer <credential>

No API key is needed. The credential expires after the issuer's token TTL, so exchange a fresh one for each run.

API Examples​

Curl​

This command will returns the organizations for this API KEY using the basic auth header.

curl -H "Authorization: Basic `echo -n $AKUITY_API_KEY_ID:$AKUITY_API_KEY_SECRET | base64`" https://akuity.cloud/api/v1/organizations

This is the same command, but we are using the basic auth -u flag in Curl. Which is a little easier since we don't need to Base64 encode the header ourselves.

curl -u $AKUITY_API_KEY_ID:$AKUITY_API_KEY_SECRET https://akuity.cloud/api/v1/organizations