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:
1
mutation GetSpaceliftToken($token: String!){
2
oauthUser(token:$token){
3
jwt
4
}
5
}
Copied!
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.
If you want to access the API reliably in an automated way, we suggest using the second approach since Spacelift tokens expire after an hour.
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:
1
Please use the following API secret when communicating with Spacelift
2
programmatically:
3
​
4
$your-api-secret
5
​
6
Please add this snippet to your .terraformrc file if you want to use this API
7
key to access Spacelift-hosted Terraform modules outside of Spacelift:
8
​
9
credentials "spacelift.io" {
10
token = "$your-modules-token"
11
}
Copied!
Make sure you persist this data somewhere on your end - we don not store the token and it cannot be retrieved or recreated afterwards.
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:
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.
API keys are in fact virtual users and are billed like regular users, too. Thus, each API key used (exchanged to a token) during any given billing cycle counts against the total number of users.
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:
Please replace the URL in the above example with the one pointing to your Spacelift account.