In this article we disclose the full GraphQL schema used by the web app GUI. A smaller subset of this API is also used by the Terraform provider. Both can be accessed at the /graphql endpoint of your account using POST HTTP method.

Authenticating with the API

In order to use the API, you will need a bearer token. There are three ways of obtaining these. The easiest way is to log in to the right Spacelift account and retrieve the token from local storage:

The second option - only available to those using GitHub as their identity provider - is to use a personal GitHub token and exchange it for Spacelift's one:

mutation GetSpaceliftToken($token: String!) {
  oauthUser(token: $token) {
    jwt
  }
}

The third option is to use API keys, described in their separate section.

We suggest using a purpose-built GraphQL client to maintain your sanity. For example, we had great success with Insomnia REST Client.

API key management

Spacelift supports creating and managing machine users with programmatic access to Spacelift API. These are called API keys, and can be created by Spacelift admins through the Settings panel.

In order to create a new API key, please navigate to the API keys section of the admin Settings panel.

The API key creation form will allow you to specify an arbitrary key name, along with the Admin setting and the list of teams. If the key is given admin privileges, it has full access to the Spacelift API and won't be subject to access policies.

For non-administrative keys you may want to add a virtual list of teams that the key should "belong to" so that existing access policies based on GitHub teams or SAML assertions can work with your API keys just as they do with regular users.

Without further ado, let's create a non-administrative API key with virtual membership in two teams: Developers and DevOps:

Once you click the Add key button, the API key will be generated and a file will be automatically downloaded. The file contains the API token in two forms - one to be used with our API, and the other one as a .terraformrc snippet to access your private modules outside of Spacelift:

The config file looks something like this:

Please use the following API secret when communicating with Spacelift
programmatically:
​
$your-api-secret
​
Please add this snippet to your .terraformrc file if you want to use this API
key to access Spacelift-hosted Terraform modules outside of Spacelift:
​
credentials "spacelift.io" {
  token = "$your-modules-token"
}

Using the API key

In order to use your newly generated API key in a program, you will first need to exchange it for a regular token using a GraphQL mutation:

mutation GetSpaceliftToken($keyId: ID!, $keySecret: String!) {
  apiKeyUser(id: $keyId, secret: $keySecret) {
    jwt
  }
}

Note that the key ID is the alphanumeric identifier shown in the GUI in fixed-width font next to the key name. The key secret can be found in the file that gets automatically generated when the API key is created.

The received JWT is valid for an hour, so if you're accessing Spacelift API from a long-running process you will need to make sure that they key is recreated every time it expired. In order to help with that, you can retrieve the validUntil field (Unix timestamp of the expiration, in seconds) of the apiKeyUser along with the raw JWT.

GraphQL schema

Our GraphQL schema is self-documenting. The best way to view the latest documentation is using a dedicated GraphQL client like Insomnia or Postman. Here's how:

​