Crusoe Cloud API (v1alpha2)
Download OpenAPI specification:Download
Reference information for Crusoe Cloud's REST API.
Crusoe Cloud is currently in alpha. If you do not currently have access, please request access to continue.
Crusoe Cloud's REST API can be used to programmatically control resources such as creating Virtual Machines or fetching information about your organization.
Base URL and version
Crusoe Cloud's API is hosted at https://api.crusoecloud.com
.
The current version while we are in private alpha is /v1alpha2
.
Authentication
In order to authenticate to Crusoe Cloud's API, you must sign all requests using the following algorithm.
To begin creating a signed request, you need several pieces of information about the request being made:
- The version of the signature being generated
- The API access key ID and secret key
- The signature payload
- A timestamp for approximately when the request was created and sent, to prevent replay attacks
Once you have this information, you can send requests with the X-Crusoe-Timestamp
and Authorization
headers to authenticate to the API:
curl https://api.crusoecloud.com/v1alpha2/... \
-H "X-Crusoe-Timestamp: <RFC3339 timestamp>" \
-H "Authorization: Bearer <version:access_key_id:base64_encoded_signature>" \
...
Signature version
The current version of the signature is 1.0
.
Getting an API access key and secret key
You can create an API access key and secret key by following the instructions in "Manage your API Keys".
Generating a signature
The signature payload consists of the following information, separated by newline ("\n") characters:
http_path
canonicalized_request_params
http_verb
timestamp_header_value
If there is no value (for example, no query params), then the line contains a single newline character.
The payload is used to generate a SHA256 HMAC signature, using a raw-urlsafe-base64 decoded version of the secret key as the HMAC secret key. The resulting HMAC signature is then base64 encoded and concatenated to the version
and access_key_id
using the :
character.
Example
As an example, imagine we have:
- An API access key ID (
gYFONy-6QKS1acgUEQrR4Q
) and secret key (uZFGf918DmiBUwBWv8lnEg
) - A
GET
request being made to/v1alpha2/vms/types
- At
2022-03-01T01:23:45+09:00
This would result in the following payload:
/v1alpha2/vms/types
GET
2022-03-01T01:23:45+09:00
The payload is then put through: raw_url_base64_encode(hmac_sha256("/v1alpha2/vms/types\n\nGET\n2022-03-01T01:23:45+09:00\n", raw_url_base64_decode("uZFGf918DmiBUwBWv8lnEg")))
.
The output is then concatenated together with 1.0:6QKS1acgUEQrR4Q
(the version and access key ID) and placed in the authorization header:
curl https://api.crusoecloud.com/v1alpha2/vms/types \
-H "X-Crusoe-Timestamp: 2022-03-01T01:23:45+09:00" \
-H "Authorization: Bearer 1.0:gYFONy-6QKS1acgUEQrR4Q:ZWFmMzVjMWMwODExNDc0OGY2ZTRmMzI0Y2UxOTI3YWQ2OTcwNmIzZTM4YWJmYjRkYWVjODBlYWE4MzY2ZGZkYw"
Response samples
- 200
- 401
- 500
{- "instances": [
- {
- "commitment_end": "2021-12-03T19:58:34Z",
- "commitment_period": 6,
- "created_at": "2021-12-03T19:58:34Z",
- "id": "ca39e669-47ee-456b-968d-303234fbf99f",
- "name": "my-first-vm",
- "product_name": "a100.2x",
- "role_id": "09ae8411-0fbb-411c-898c-2b8f19622ae1",
- "ssh_destination": "12.21.12.21:22",
- "state": "RUNNING"
}
]
}
Create a new VM instance owned by the logged in user.
Request Body schema: application/json
commitment_period | integer <int64> |
image_checksum | string |
image_id | string |
name required | string |
product_name required | string |
role_id required | string |
shutdown_script | string |
ssh_public_key required | string |
startup_script | string |
Responses
Request samples
- Payload
{- "commitment_period": 6,
- "image_checksum": "120EA8A25E5D487BF68B5F7096440019",
- "image_id": "9f161e28-b629-442c-951c-77c68199f36e",
- "name": "my-first-vm",
- "product_name": "a100.2x",
- "role_id": "09ae8411-0fbb-411c-898c-2b8f19622ae1",
- "shutdown_script": "\"#!/bin/bash\\necho'goodbye'\"",
- "ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCspdG97nTS/h4PEPq2QD2RYVK1jxFXLFZuSDMI8Rtxpucl6LDZLOghEYoj13lxKQnGtcsM3Iu68lh+4YgZe7CbI6cc/TxPbeAX2HJTqDh0J7+GAlLBHK9tsepC0QlhIDiazJptOPDZ3cesCBXdxSnzEbhDaqgYOfl393cp1fCeOKRIDWEP3H9CM25dCbWF66sTDziLsojJ9dMnxhgKm9/JkZc5gYncLT/2Ey+VWfV9Fs65mGUrBbQOn3c8S/nEk6WRcYn4PFOnIp0Mz+Chb50iCJrW677pllLnkTGSU+4c0H9J5z4HDG0I+91RoiQ0QsayFTYO1JtSn+THLuq98V+D",
- "startup_script": "\"#!/bin/bash\\necho'hello'\""
}
Response samples
- 200
- 400
- 401
- 403
- 500
{- "operation": {
- "completed_at": "2021-12-03T19:59:34Z",
- "metadata": { },
- "operation_id": "F6EF489C-086E-458D-B812-7962964A28C9",
- "result": { },
- "started_at": "2021-12-03T19:58:34Z",
- "state": "IN_PROGRESS"
}
}
Get status of asynchronous operations
This resource retrieves information about the status of asynchronous operations initiated by the instances resource. All operations that are either in-flight or completed but not yet queried will be returned.
query Parameters
resource_id | string Example: resource_id=452580d7-41d1-4b63-b4d7-4e4e21e95f96 |
Responses
Response samples
- 200
- 401
- 403
- 500
{- "operations": [
- {
- "completed_at": "2021-12-03T19:59:34Z",
- "metadata": { },
- "operation_id": "F6EF489C-086E-458D-B812-7962964A28C9",
- "result": { },
- "started_at": "2021-12-03T19:58:34Z",
- "state": "IN_PROGRESS"
}
]
}
Get status of a single asynchronous operation
This resource retrieves information about the status of an asynchronous operation initiated by the instances resource. Only information about the operation specified in the path will be returned, or an HTTP 403 will be returned if the operation does not exist, was not initiated by the logged in user, or has expired.
path Parameters
operation_id required | string |
Responses
Response samples
- 200
- 400
- 401
- 403
- 500
{- "operations": [
- {
- "completed_at": "2021-12-03T19:59:34Z",
- "metadata": { },
- "operation_id": "F6EF489C-086E-458D-B812-7962964A28C9",
- "result": { },
- "started_at": "2021-12-03T19:58:34Z",
- "state": "IN_PROGRESS"
}
]
}
Response samples
- 200
- 401
- 403
- 500
{- "operation": {
- "completed_at": "2021-12-03T19:59:34Z",
- "metadata": { },
- "operation_id": "F6EF489C-086E-458D-B812-7962964A28C9",
- "result": { },
- "started_at": "2021-12-03T19:58:34Z",
- "state": "IN_PROGRESS"
}
}
Change the state of a VM the logged in user owns.
path Parameters
vm_id required | string |
Request Body schema: application/json
action required | string |
commitment_period | integer <int64> |
Responses
Request samples
- Payload
{- "action": "START",
- "commitment_period": 6
}
Response samples
- 200
- 400
- 401
- 403
- 500
{- "operation": {
- "completed_at": "2021-12-03T19:59:34Z",
- "metadata": { },
- "operation_id": "F6EF489C-086E-458D-B812-7962964A28C9",
- "result": { },
- "started_at": "2021-12-03T19:58:34Z",
- "state": "IN_PROGRESS"
}
}
Retrieve details about roles that the logged in user belongs to or owns.
If querying for roles within an organization, the logged in user must be the owner of the organization.
query Parameters
org_id | string Example: org_id=ee2a6bc3-aed5-4756-8995-9990a53d3a17 |
Responses
Response samples
- 200
- 401
- 500
{- "roles": [
- {
- "id": "09ae8411-0fbb-411c-898c-2b8f19622ae1",
- "name": "Admin",
- "organization_id": "ab4a6b00-aa5f-408e-a9fb-ac6de5eb45ab",
- "relation": "owner"
}
]
}
Update details for a role that the logged in user owns.
Requests to this resource must contain the json-encoded representation of the changes they want to make to the role. Currently only the role's name can be changed.
query Parameters
role_id required | string Example: role_id=f058d0db-2fa4-4cf2-8cf1-dfbcfe05a814 |
Request Body schema: application/json
name required | string |
Responses
Request samples
- Payload
{- "name": "Crusoe Energy"
}
Response samples
- 200
- 400
- 401
- 403
- 500
{- "role": {
- "id": "09ae8411-0fbb-411c-898c-2b8f19622ae1",
- "name": "Admin",
- "organization_id": "ab4a6b00-aa5f-408e-a9fb-ac6de5eb45ab",
- "relation": "owner"
}
}
Create a new role that will be owned by the logged in user.
The logged in user must have the permission to create roles within the organization. A successful response from this resource contains details of the created role.
Request Body schema: application/json
name required | string |
organization_id required | string |
Responses
Request samples
- Payload
{- "name": "Admin",
- "organization_id": "ab4a6b00-aa5f-408e-a9fb-ac6de5eb45ab"
}
Response samples
- 200
- 400
- 401
- 403
- 500
{- "role": {
- "id": "09ae8411-0fbb-411c-898c-2b8f19622ae1",
- "name": "Admin",
- "organization_id": "ab4a6b00-aa5f-408e-a9fb-ac6de5eb45ab",
- "relation": "owner"
}
}
Delete a role that the logged in user owns.
Delete operations cascade to VMs created under that role.
query Parameters
role_id required | string Example: role_id=f058d0db-2fa4-4cf2-8cf1-dfbcfe05a814 |
Responses
Response samples
- 401
- 403
- 500
{- "code": "401",
- "message": "bad_credential"
}
Retrieve the list of users who are members of a role the logged in user owns.
query Parameters
role_id required | string Example: role_id=f058d0db-2fa4-4cf2-8cf1-dfbcfe05a814 |
Responses
Response samples
- 200
- 400
- 401
- 403
- 500
{- "membership": [
- {
- "id": "d8f58dfd-dd86-4ee4-8f01-643e6d0f15bb",
- "name": "John Doe",
- "relation": "member"
}
]
}
Update the membership for a role, and supports adding and removing users.
When removing a user, the association between the user and the role will be deleted.
query Parameters
role_id required | string Example: role_id=f058d0db-2fa4-4cf2-8cf1-dfbcfe05a814 |
Request Body schema: application/json
add required | Array of strings |
required | Array of objects (RelationUpdate contains information needed to grant a user permissions.) |
remove required | Array of strings |
Responses
Request samples
- Payload
{- "add": [
- "05d42579-47a2-4739-beb5-aef5b90626a4"
], - "grant": [
- {
- "id": "465a1fb5-f37e-4483-ad36-bf994efcb170",
- "relation": "member"
}
], - "remove": [
- "37021bb9-3620-42d9-ab46-da0ec3078769"
]
}
Response samples
- 401
- 500
{- "code": "401",
- "message": "bad_credential"
}
Response samples
- 200
- 401
- 500
{- "entities": [
- {
- "billing": {
- "balance": "$1000.00",
- "delinquent": false,
- "has_valid_payment_method": true
}, - "id": "ab4a6b00-aa5f-408e-a9fb-ac6de5eb45ab",
- "name": "Crusoe Energy",
- "relation": "owner"
}
]
}
Update details for an organization that the logged in user owns.
A successful response from this resource will contain the updated organization details.
query Parameters
org_id required | string Example: org_id=ab4a6b00-aa5f-408e-a9fb-ac6de5eb45ab |
Request Body schema: application/json
organization_name required | string |
Responses
Request samples
- Payload
{- "organization_name": "Crusoe Energy"
}
Response samples
- 200
- 400
- 401
- 403
- 500
{- "entity": {
- "billing": {
- "balance": "$1000.00",
- "delinquent": false,
- "has_valid_payment_method": true
}, - "id": "ab4a6b00-aa5f-408e-a9fb-ac6de5eb45ab",
- "name": "Crusoe Energy",
- "relation": "owner"
}
}
Create a new organization owned by the logged in user.
A successful response from this resource will contain the json encoded organization details.
Request Body schema: application/json
organization_name required | string |
Responses
Request samples
- Payload
{- "organization_name": "Crusoe Energy"
}
Response samples
- 200
- 401
- 500
{- "entity": {
- "billing": {
- "balance": "$1000.00",
- "delinquent": false,
- "has_valid_payment_method": true
}, - "id": "ab4a6b00-aa5f-408e-a9fb-ac6de5eb45ab",
- "name": "Crusoe Energy",
- "relation": "owner"
}
}
Delete an organization owned by the logged in user.
Delete operations will cascade to roles and VMs, and all members will be removed from the organization.
query Parameters
org_id required | string Example: org_id=ab4a6b00-aa5f-408e-a9fb-ac6de5eb45ab |
Responses
Response samples
- 401
- 403
- 500
{- "code": "401",
- "message": "bad_credential"
}
Update the membership for an organization, as well as granting permissions to existing members.
For inviting and removing users from an organization, the logged in user must be the owner of the organization. For accepting an invite, the logged in user must have been invited to the organization.
Request Body schema: application/json
accept | boolean |
required | Array of objects (RelationUpdate contains information needed to grant a user permissions.) |
Array of objects (Invitee) | |
remove required | Array of strings |
Responses
Request samples
- Payload
{- "accept": true,
- "grant": [
- {
- "id": "465a1fb5-f37e-4483-ad36-bf994efcb170",
- "relation": "member"
}
], - "remove": [
- "aacfd263-9074-4d0a-93ae-d10551ad1094"
]
}
Response samples
- 401
- 500
{- "code": "401",
- "message": "bad_credential"
}
Create a new prospective customer in Crusoe Cloud.
Request Body schema: application/json
company required | string |
email required | string |
name required | string |
source required | string |
use_case required | string |
Responses
Request samples
- Payload
{- "company": "crusoe",
- "name": "john",
- "source": "portal",
- "use_case": "training model to minimize energy usage"
}
Response samples
- 200
- 500
{- "success": true
}
Response samples
- 200
- 401
- 500
{
}
Update user details for the logged in user.
A successful response from this resource wil contain the updated user details.
Request Body schema: application/json
email required | string |
name | string |
Responses
Request samples
- Payload
{- "name": "John Doe"
}
Response samples
- 200
- 401
- 500
{
}
Response samples
- 200
- 401
- 500
{- "ssh_keys": [
- {
- "created_at": "2022-01-24T20:13:35.328Z",
- "fingerprints": {
- "md5": "bf:60:fa:cc:9f:42:1f:5e:23:9e:ed:d2:69:d8:76:93",
- "sha256": "tARFxQkVHeqm6TzqpI897QsHVdgZlxgL2/YhVltmEUk"
}, - "id": "0b880f48-6a97-408f-8351-3cc30871e010",
- "name": "public key 1",
- "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICpuH/fqCFLbAConChyVH6rZzSaxlnHSwQk6qvtPsf5E"
}
]
}
Register a new SSH public key to the logged in user.
A successful response from this resource wil contain the created SSH key details.
Request Body schema: application/json
name required | string |
public_key required | string |
Responses
Request samples
- Payload
{- "name": "John Doe",
- "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICpuH/fqCFLbAConChyVH6rZzSaxlnHSwQk6qvtPsf5E"
}
Response samples
- 200
- 400
- 401
- 500
{- "ssh_key": {
- "created_at": "2022-01-24T20:13:35.328Z",
- "fingerprints": {
- "md5": "bf:60:fa:cc:9f:42:1f:5e:23:9e:ed:d2:69:d8:76:93",
- "sha256": "tARFxQkVHeqm6TzqpI897QsHVdgZlxgL2/YhVltmEUk"
}, - "id": "0b880f48-6a97-408f-8351-3cc30871e010",
- "name": "public key 1",
- "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICpuH/fqCFLbAConChyVH6rZzSaxlnHSwQk6qvtPsf5E"
}
}
Response samples
- 200
- 401
- 500
{- "tokens": [
- {
- "access_key": "Hm11C1coQZm2+Aihn9ofYg",
- "alias": "token1",
- "created_at": "2021-11-03T22:16:27Z",
- "expires_at": "2021-12-03T19:58:34Z",
- "last_used": "2021-11-03T22:22:55Z"
}
]
}
Create a new token owned by the logged in user.
A successful response from this resource will contain json-encoded details of API token. This is the only time the customer will be able to view the secret key associated with the token.
Request Body schema: application/json
alias required | string |
expires_at required | string |
Responses
Request samples
- Payload
{- "alias": "token1",
- "expires_at": "2021-12-03T19:58:34Z"
}
Response samples
- 200
- 401
- 500
{- "token": {
- "access_key": "R7p5XctCQMuGlpVBmVdqzA",
- "alias": "newtoken",
- "created_at": "2021-11-03T22:16:27Z",
- "expires_at": "2021-12-03T19:58:34Z",
- "secret_key": "HrbZ3VTUb2YNAq53Md1EsA"
}
}