Overview

Authentification

Requests to the API are authenticated with a bearer token using the HTTP header Authorization: Bearer <token>. Tokens can be created by clicking on your username on the bottom left of the Scalr UI and selecting "Personal Access Tokens". Service account tokens can also be created for production usage.

If the token is not supplied or it is invalid, Scalr returns the status response HTTP 401 Unauthorized and a JSON API error object. Status response 401 is only used when there are problems with the authentication token. If the token is valid but the requester does not have the required permissions for the endpoint/method then Scalr will return the status response HTTP 404 Not found.

API Versioning and Path

Versioning will be introduced once the stable profile is released. The Scalr API has the current major version “v3” with a path prefix of /api/iacp/v3

If there is a future change to API semantics the version will increment to “v4”.

API Profiles

The preview profile is the only profile that currently exists, the stable and deprecated profiles will be released soon.

The API will have the following profiles available to enable the implementation and deprecation of features in a controlled and predictable manner:

  • preview: Experimental functionality for end users. Available in the public OpenAPI specification. Features in this profile are considered “beta”. API interfaces might change between on-prem feature releases, or at any time on Hosted Scalr. Customers should only use preview in non-critical workflows in order to test and provide feedback. Features from the “preview” profile might be promoted to stable or may be dropped.

  • stable (coming soon): The API mainline. It is the default profile for all API clients. This profile is highly backward compatible between two feature releases, and the process of deprecating features is described below. When it is decided to remove a stable feature from the API the feature must be first moved into to the “deprecated” profile.

  • deprecated (coming soon): The profile where features are retiring, before their removal from the API. Features can move into this profile from the “stable”, and the API interface remains untouched until removal from the product.

The profile is set using the header Prefer: option as shown in this example.

curl -s -X ${HTTP_OP} ${API_URL}${THE_PATH} \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/vnd.api+json" \
      -H "Prefer: profile=preview" \
            --data "@data.json"

API Feature Deprecation

Any deprecation will be communicated through the API specification, documentation, and HTTP API responses.

  • preview: Feature removal will be communicated 2 weeks in advance.
  • stable: Features planned for deprecation will remain in stable profile for 3 months after the announcement of planned deprecation. After 3 months the feature will be moved into the deprecated profile.
  • deprecated: After the feature is moved into the deprecated profile, it is will be available for use for at least 3 more months.

API Format

The Scalr API is a REST API. It follows JSON:API v1.0 semantics for requests and responses.

JSON API Responses and Inputs

Responses from the API will be JSON Documents.

For POST and PATCH methods a JSON API document is required as the request payload. This is an example of payload to create a workspace.

{
    "data": {
        "attributes": {
            "auto-apply": true,
            "name": "workspace-name",
            "operations": true,
            "tags": [
                {
                    "name": "tag-name",
                    "value": "tag-value"
                }
            ],
            "terraform-version": "0.12.28",
            "vcs-repo": {
                "branch": "master",
                "identifier": "vcs-xxxxxxxxx"
            },
            "working-directory": "sub-dir"
        },
        "type": "workspaces"
    }

The JSON must be structured as follows

  • Top-level data property.
  • data.type property as defined in the API method specification.
  • Typically will include data.attributes containing the attributes of the object with possibly other nested objects.

The documentation will reference nested attributes using the format shown in this example.

{
    "data": {
        "attributes": {
            "auto-apply": true
        }
    }
}

referenced as data.attributes.auto-apply.

Method Parameters

For some POST, PATCH and DELETE methods it is necessary to specify the relevant object ID as part of the endpoint path. This may be the only parameter or may also require a JSON object to be passed as well. The object ID place holder will be shown using {...} notation as shown in this example.

POST /api/iacp/v3/workspaces/{workspace}/actions/unlock

For GET methods it may be necessary to pass in query parameters such as filters, using the ?filter[attribute]=value format. Depending on the tooling, it may also be necessary to encode the [] using %5B and %5D. The documentation assumes the encoding is required and describes the method as shown in this example.

GET /api/iacp/v3/runs?filter%5Bworkspace%5D=string HTTP/1.1

The “parameters” section for each method describes the query parameters for the method and specifies which ones are required and which are optional. See below for details on using the pagination parameters.

Pagination Parameters

Pagination is supported for any method that returns an array of objects. The default is to return the first 20 objects but this can be altered by specifying a page number and size as parameters to the query in the following format.

...?page[number]=3&page[size]=25

This example would return objects from number 51 to 75 (if these exist).

The links and meta attributes will contain pagination data to make it easy to re-query the API for additional objects.

{
    "links": {
        "first": "https://my-account.scalr.io/api/iacp/v3/runs?filter%5Bworkspace%5D=ws-t4qmoc3kbumpoug?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "last": "https://my-account.scalr.io/api/iacp/v3/runs?filter%5Bworkspace%5D=ws-t4qmoc3kbumpoug?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "next": null,
        "prev": null,
        "self": "https://my-account.scalr.io/api/iacp/v3/runs?filter%5Bworkspace%5D=ws-t4qmoc3kbumpoug?page%5Bnumber%5D=1&page%5Bsize%5D=20"
    },
    "meta": {
        "pagination": {
        "current-page": 1,
        "next-page": null,
        "prev-page": null,
        "total-count": 2,
        "total-pages": 1
        }
    }
}

Example Usage

Below is the syntax required to make an API call in shell script using curl

curl -s -X ${HTTP_OP} ${API_URL}${THE_PATH} \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/vnd.api+json" \
      -H "Prefer: profile=preview" \
            --data "@data.json"

This is an example of what a complete call to create a workspace might look like.

curl -s -X POST HTTPS://my-account.scalr.io/api/iacp/v3/workspaces \
      -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxx" \
      -H "Content-Type: application/vnd.api+json" \
      -H "Prefer: profile=preview" \
            --data "@create-workspace.json"

This is an example of the data required for a workspace bound to a VCS.

{
    "data": {
        "attributes": {
            "auto-apply": true,
            "name": "example",
            "queue-all-runs": true,
            "terraform-version": "0.13.5",
            "vcs-repo": {
                "branch": "master",
                "identifier": "scalr-eap/vcs-example",
            }
        },
        "relationships": {
            "environment": {
                "data": {
                   "id": "env-t2fcrq6h1v3nf0g",
                   "type": "environments"
                }
            },
            "vcs-provider": {
                "data": {
                   "id": "vcs-82d594bacd10",
                   "type": "vcs-providers"
                }
            }
        },
        "type": "workspaces"
    }
}

OpenAPI Spec

The OpenAPI specification for Scalr can be found here: https://scalr.io/api/iacp/v3/openapi-preview.yml

Rate Limit

The Scalr API is rate limited to prevent slow response times or downtime due to excessive usage. The limit is 500 requests per minute.

The expected error when hitting the rate limit is 429 - Rate Limit Exceeded.

If this is impacting your work in Scalr, please contact support to review the possibility of increasing the limit for your account.