Sign inTry Free

Management API Overview

On this page

SingleStore provides the Management REST API to create and manage workspace groups and workspaces. This RESTful API allows you to perform the following operations:

  • Create, update, or delete workspace groups, request information on available workspace groups, list the workspace groups

  • Create or delete workspaces, request information on workspaces, list the workspaces

  • Create, update, or delete private connections, request information on private connections

  • Create, update, or delete a team for the current organisation, request information on a team

  • Create, update, or delete a job, request information on jobs, list the jobs

  • Create, update, or delete a folder in a Stage, request information on a folder

  • Upload, download, modify, or delete a file in a Stage

  • Create, update, or delete a secret, request information on a secret, list the secrets

  • Request information on current organization, get raw compute and storage usage information for your organization

  • Request audit log entries

  • List the regions for a user

The Management API supports HTTP Bearer authentication, which must be used in conjunction with SSL (HTTPS) for secure communication over the network. API calls made over HTTP will fail. For more information, see Management API Overview.

Authorization

The Management API authenticates requests using a unique, hex-encoded alphanumeric key. You can generate this API key on the Cloud Portal.

When a user is a member of multiple organizations, they can have multiple API keys, one for each organization. The API key defines the operations that a user can perform.

Generate an API Key

Follow these instructions to generate API keys:

  1. On the Cloud Portal, in the navigation pane, select your organization.

  2. In the navigation pane, select Configuration > API keys > Active Keys > Create API key.

  3. Specify a name and expiration date for the API key, and select Create.

Important

The API key is displayed only once. Be sure to copy and securely store the API key.

Revoke an API Key

To revoke an API key, navigate to the API keys section under Configuration on the Cloud Portal. On the Active Keys tab, select the delete icon under the Actions column for the API key, and select Revoke.

API keys that are not manually revoked expire on the expiration date defined while creating the API key. A revoked API key cannot be reinstated.

Control Access to the API

SingleStore recommends using IP Allowlist to secure inbound access to workspaces using the Management API.

To allow an IP address, login to the Cloud Portal. Under your organization, select Configuration > API Keys > Security > Edit > Only allow access from specified IP addresses. Under IP Allowlist, add the IP address to allow.

A dialog box for editing IP Address Access.

By default, IP Allowlist is set to Allow access from anywhere, which allows access to anyone with the API key.

Access the Management API

SingleStore’s Management API supports HTTP Bearer authentication. To access the API, you must provide your API key in the Authorization header in each HTTP request. An example Authorization header is as follows.

Authorization: Bearer 28790ecd46256d9024e7b21a737493b2ed2872e6883808a87843d1ce9839d0d3

While making API calls through an HTTP client (such as cURL), you can pass the API key using the -H parameter:

curl -X 'GET' \
  'api_endpoint_url' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <API_key>'

Workspaces

A workspace is an independent logical deployment of compute resources which can be used to run a workload in lieu of a cluster. A database can be shared across multiple workspaces through R/W (read/write) and R/O (read only) attachments. Contact SingleStore Support for access to the workspaces and the API.

Each workspace is a part of a workspace group, which allows configuration and management of workspaces. An organization can have multiple workspace groups, and each workspace group can have up to five workspaces.

Connect to a Workspace

Once a workspace becomes active, use the workspace endpoint to establish a SQL connection in conjunction with the admin user and password (password for the workspace group). Here is a sample connection:

mysql -h svc-a6df2ae8-85cc-4c59-b26a-66516de053d8-1-dml.aws-cancentral-1.svc.singlestore.com -u admin --password='QUNL@S|(})jZX1VDOp%*EMzm'

Attach a Database

After connecting to a workspace endpoint, execute the CREATE DATABASE command to create the specified database and attach it to the workspace in the read-write mode.

Refer to Attach a Database to a Workspace for more information.

Detach a Database

Refer to Detach a Database from a Workspace for more information.

Manage the API using Golang Client

The singlestore-go repository is a collection of SingleStore Golang SDKs. The modules in the management package in the Golang SDK can be used to interact with the Management API.

To import the SDK, add the following line to your *.go file:

import "github.com/singlestore-labs/singlestore-go/management"

For more information, see Management API Golang SDK documentation. Here’s a sample project that uses the Management API Golang client.

References

In this section

Last modified: September 25, 2024

Was this article helpful?

On this page

Was this article helpful?