API Token

To use the Scalr API, a service account or personal token can be used. To obtain a personal token, click your user ID in the bottom left of the Scalr UI, then select personal access tokens. Create the token and copy it.

To obtain a service account token, navigate to the security tab at the admin scope, go to IAM, and service accounts:

Find more information on service accounts here.

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

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 Feature Deprecation

Any deprecation will be communicated through the API specification, documentation, and HTTP API responses. Features planned for deprecation will remain in the API for 3 months after the announcement of the planned deprecation. After 3 months the feature will be completely removed.

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
        }
    }
}

Filtering Records

Scalr API supports advanced filtering using the filter query parameter. Filters follow the JSON:API conventions with some extensions for expressing conditions. The typical format of a filter is:

?filter[<resource>][<attribute>]=<condition>
?filter[<name>]=<condition>

<resource> is an optional grouping such as workspace, used to namespace filters when filtering nested or related objects.
<attribute> is the name of the field to filter by.
<condition> is the filtering operation, with the format depending on the type of condition being used. If supported, several comma-separated values can be provided in the condition.
<name> - some filters use custom naming when it is not directly mapped to an attribute, e.g. filter[owned-by-me].

Available filter conditions include:

Condition	Description	Example
`eq`	Equals (default, can be omitted)	`eq:env-xxx`
`in`	In list	`in:env-xxx,env-yyy`
`all`	Has all values (e.g. tags)	`all:tag1,tag2`
`gte`	Greater than or equal to	`gte:123`
`lte`	Less than or equal to	`lte:123`
`like`	Pattern matching (prefix match)	`like:nam`
`ne`	Not equal	`ne:env-xxx`
`between`	Between two values (typically for dates or numbers)	`between:100,200`

Examples:

GET /resource?filter[status]=pending
GET /resource?filter[workspace][name]=like:dev
GET /resource?filter[environment]=ne:env-xxx
GET /resource?filter[created-at]=between:2021-01-01T00:00:00Z,2021-01-31T23:59:59Z
GET /resource?filter[environment]=in:env-xxx,env-yyy&filter[workspace]=in:ws-xxx,null

To understand which filters are available for each endpoint, refer to the OpenAPI specification.

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" \
            --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" \
            --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-public.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.