Spheron API
Spheron API is an API that give users access over our platform, providing all the resources that is available to you, exposed as HTTPS endpoints.
API style
REST API
REST API called “Representational State Transfer” and it makes the APIs relatively easy to use and discover. Spheron API is a REST-styled API that makes all data available. REST makes data and functionality available as resources, using unique URLs. To request a data or resource,you just need to provide its URL.
API Basics
Our API is exposed as an HTTP/1 and HTTP/2 service over SSL. All endpoints live under the URL
https://api-v2.spheron.network
and follow the REST architecture.
HTTP and TLS
The API supports HTTP versions 1, 1.1, and 2, although HTTP/2 is preferred. TLS versions 1.2 and 1.3 are supported, with resumption.
Content Type
All requests made to the API must be encoded as JSON with the Content-Type: application/json
header. If not otherwise specified, responses from the Spheron API, including errors, are encoded exclusively as JSON as well.
For new users
Before creating an access token for authentication, you need to sync your GitHub or GitLab account to give spheron access. Click here for more instructions about granting access to your repository.
Authentication
Spheron Access Tokens are required to authenticate and use the Spheron API.
Authorization: Bearer <TOKEN>
NOTE: Use the Authorization header followed by an access token.
Creating an Access Token
Access Tokens can be created and managed from inside your account settings.
- Go to your profile icon in your spheron dashboard app and click on it.
- Click on settings from the image above to go to your settings page and navigate to the Tokens in your Account Settings.
- Click Create to open a new Access Token.
- Enter a descriptive name and choose the scope from the list of Organization in the drop-down menu and select an expiration date for the token and click create token.
The scope ensures that only your specified Organization can use an Access Token. Once you've created an Access Token securely store the value as it will not be shown again.
Expiration
Setting an expiration date on an Access Token is highly recommended and is considered one of the standard security practices that helps keep your information secure. You can select from a default list of expiration dates ranging from 1 day to 1 year. You can view the expiration date of your Access Tokens on the tokens page.
Failed Authentication
If authentication is unsuccessful for a request, the error status code 403 is returned.
Versioning
All endpoints and examples are designated with a specific version. Versions vary per endpoint and are not global. The response shape of a certain endpoint is not guaranteed to be fixed over time. In particular, we might add new keys to responses without bumping a version endpoint, which will be noted in the changelog.
To ensure the security and correctness of your application, make sure to only read the keys from the response that your application needs. Don't proxy entire responses to third-parties without validation. Old versions of each endpoint are supported for as long as possible. When we intend to deprecate, we will notify users in the changelog section.
Endpoint versions follow the base URL and come before the endpoint. For example:
https://api-v2.spheron.network/v1/deployments
API response codes
REST APIs use the Status-Line part of an HTTP response message to inform clients of their request’s overarching result. Spheron API uses the standardized status codes from 100 to 511.
Code | Description |
---|---|
200 | Successfully fetch Organization information Successfully fetch Array of coupons Successfully fetch Array of invite users Successfully fetch Project information Successfully Added environment variables Successfully Create a deployment |
401 | This means that the request was unauthorized |
API Reference
We have generated a swagger documentation (opens in a new tab) for all the API endpoints that developers can access using their API token.