Fundamentals and Authentication

Basics

The Scalarium API is currently in an early preview stage and in private beta. It's not feature complete, as we focussed on customer demand first, and will flesh out missing details as we go. Let us know if you'd like to participate. The code examples use RestClient and Ruby code, but should be easily applicable for use with other languages. Let us know if there's something we should clarify. We'll eventually start building libraries for simpler use than directly talking to the API through HTTP, but we want to flesh out some more details first.

The API currently includes:

• Listing clouds, their roles and instances
• Creating clouds
• Creating, starting, stopping and rebooting instances
• Listing and deploying applications
• Getting the status and logs for a deployment for every instance involved

The main endpoint for the API is https://manage.scalarium.com/api, and it's versioned, starting with version 1, all communication is done using JSON. The version however, is not part of the URI, it needs to be set as an Accept header for every request. Use the type application/vnd.scalarium-v1+json to specify the proper version.

Scalarium API Settings

To authenticate against the API, you need to enable API access for the user accounts require using it. Scalarium automatically generates an API token for every new user. The token is the means of authentication used by the API, so be careful not to give it into the wrong hands. Access is disabled by default, so you need to enable it for each user.

Every user can see his API token in the settings.

In the case that a token has been compromised, you can always go back to the user management settings in Scalarium and generate a new one.

Authenticating

To authenticate, use the header field X-Scalarium-Token to provide your personal API token. That's it. For all requests, you need to specify the token and the versioning Accept header.

RestClient.get('https://manage.scalarium.com/api/clouds',
                     'X-Scalarium-Token' => '1234',
                     'Accept' => 'application/vnd.scalarium-v1+json'

This should give you a nice JSON list of all the clouds in your account.

An alternative using curl looks like this:

curl -X GET https://manage.scalarium.com/api/clouds -H "X-Scalarium-Token: 1234" -H "Accept: application/vnd.scalarium-v1+json"