SpaceONE API

Introduction to SpaceONE API

SpaceONE provides all features as Open APIs, allowing integration with external systems and process automation.

How to Use the API

1. Create an App
To use the SpaceONE API, you first need to create an App in the SpaceONE console.
When creating an app, you’ll receive a client_secret that is used for API authentication.

2. API Request
When making REST API requests, set the client_secret obtained from [1. Create an App] as the Bearer Token and call the endpoint.
You can check the available API information through Swagger or API Documentation .

API Permissions

SpaceONE provides three levels of permission:

Domain Admin: Access to all resources
Workspace Owner: Access to all resources within the workspace
Workspace Member: Access only to designated project resources within the workspace

ℹ️

Domain Admin and Workspace permissions have different app creation locations, so please refer to the guide below.

1. Create an App

After creating an app, you’ll receive the client_secret information to be set as Bearer Token for API requests.

1-1. Create an App as Domain Admin

Switch to Admin Mode

Create an App

Go to the left menu tab and select [User & Access Management > Apps], then click the [Create] button.

Set the name, role, and tag, then click the [Confirm] button.

Copy the Created App Token

Click [More Info] in the [Client ID] field.
Copy the client_secret data from [More Info] or download it as [JSON Download].

1-2. Create an App as Workspace Owner & Workspace Member

Exit Admin Mode or Access Workspace Mode

If you are in Admin mode, exit and access the workspace you can access.

ℹ️

If you don’t have Domain Admin permissions, this toggle won’t appear.

Create an App

Set the name, role, and tag to create an app.
To create an app as Workspace Member, click the [Project Assignment] toggle and select the project group or project.

ℹ️

If you assign a project group, the app can access all projects under it.

Copy the Created App Token

Click [More Info] in the [Client ID] field.
Copy the client_secret data from [More Info] or download it as [JSON Download].

2. API Request

2-1. REST API Call

API Structure and Components

SpaceONE’s API has its own API format.

It’s not RESTful, and Method is used to indicate action instead of verb.
All API methods except for some (service check, reflection, etc.) are POST.

The configuration for sending a request is as follows.

Item	Value
Base URL	https://console-v2.kr1.api.spaceone.megazone.io
URL Format	/{`service`}/{`resource`}/{`verb`}
Method	`POST`
Header	Authorization: Bearer {`client_secret`}

ℹ️

The components of URL Format are as follows.

service: Each microservice (e.g., Identity, Inventory, etc.)
resource: Specific resources within a microservice (e.g., Identity > Workspace, Inventory > Collector, etc.)
verb: Action to perform on the resource (e.g., create, get, list, delete, etc.)

For example, inventory > collector > list means to retrieve a list of Collector resources in the Inventory service.

REST API Call Example

CURL

curl -X 'POST' \
  'https://{Base URL}/{Service}/{Resource}/{Verb}' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_secret}'\
  -d '{<Refer to API Documentation for appropriate data input>}'

Python

import requests

token = input("Enter your client secret (token): ")
base_url = input("Enter the base URL (e.g., https://www.example.com): ")

def dispatch_request(service:str, resource:str, verb:str, data:dict):
    url = f"{base_url}/{service}/{resource}/{verb}"
    headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

    return requests.post(url, headers=headers, json=data)

if __name__ == "__main__":
    response = dispatch_request(service="inventory", resource="region", verb="list", data={})
    print(response.json())

Check Supported API

2-2. Call Using CLI

cfctl is a powerful CLI designed for interacting with SpaceONE services. You can manage and control SpaceONE resources smoothly using cfctl.

ℹ️

Please refer to the corresponding guide document for cfctl installation.

Set Domain Address

Set the domain address to {your_domain_url}.

$ cfctl setting init proxy {your_domain_url} --app

Input Token Information

Enter the token issued by app creation to {client_secret}.

$ cfctl setting token {client_secret}

cfctl Execution

You need to input the command structure to interact with SpaceONE resources through cfctl as follows.

$ cfctl {service} {verb} {resource}

$ cfctl inventory list Region

Use Cases

Asset (Inventory) View Scenario

1. View Cloud Service from Provider aws

Request

curl -X 'POST' \
  'https://{Base URL}/inventory/cloud-service/list' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_secret}'\
  -d '{
  "query": {
    "page": {
      "start": 1,
      "limit": 10
    },
    "filter": [
      {
        "key": "provider",
        "value": "aws",
        "operator": "eq"
      },
      {
        "key": "cloud_service_group",
        "value": "EC2",
        "operator": "eq"
      },
      {
        "key": "cloud_service_type",
        "value": "Instance",
        "operator": "eq"
      }
    ]
  }
}'

Response

{
  "results": [
      {
          "cloud_service_id": "cloud-svc-11111111111111",
          "name": "service-bastion",
          "state": "ACTIVE",
          "ip_addresses": [
              "10.0.138.84"
          ],
          "account": "11111111111",
          "instance_type": "t3.micro",
          "cloud_service_type": "Instance",
          "cloud_service_group": "EC2",
          "provider": "aws",
          "data": {
              "os": {
                  "os_distro": "linux",
                  "os_arch": "x86_64",
                  "os_type": "LINUX",
                  "details": "Linux/UNIX"
              },
              "aws": {
                  "ami_id": "ami-1111111111111111",
                  "ami_launch_index": 0.0,
                  "kernel_id": null,
                  "monitoring_state": "disabled",
                  "ebs_optimized": true,
                  "ena_support": true,
                  "hypervisor": "xen",
                  "placement": {
                      "GroupName": "",
                      "Tenancy": "default",
                      "AvailabilityZone": "ap-northeast-2a"
                  },
                  "iam_instance_profile": {
                      "Arn": "arn:aws:iam::11111111111:instance-profile/ems-ec2-eks-bastion-role",
                      "Id": "AAAAAAAAAAAAAAAAAAAAAAA"
                  },
                  "root_volume_type": "gp3"
              },
              "hardware": {
                  "core": 2.0,
                  "memory": 1.0
              },
              "compute": {
                  "keypair": "",
                  "az": "ap-northeast-2a",
                  "instance_state": "STOPPED",
                  "instance_type": "t3.micro",
                  "launched_at": "2023-11-09T05:58:59",
                  "instance_id": "i-0322e4fe54dfa9f0f",
                  "instance_name": "obsv-service-bastion",
                  "security_groups": [
                      {
                          "name": "bastion-sg-01",
                          "id": "sg-1111111111",
                          "display": "bastion-sg-01 (sg-1111111111)"
                      }
                  ],
                  "image": "ec2-20231107-final",
                  "account": "11111111111"
              }
          },
          "reference": {
              "resource_id": "i-111111111111",
              "external_link": "https://ap-northeast-2.console.aws.amazon.com/ec2/v2/home?region=ap-northeast-2#Instances:instanceId=i-111111111111"
          },
          "tags": {
              "aws": {
                  "Name": "service-bastion"
              }
          },
          "tag_keys": {
              "aws": [
                  "Name"
              ]
          },
          "collection_info": {
              "service_account_id": "sa-11111113c43",
              "secret_id": "secret-aaa88e9e1110",
              "collector_id": "collector-afc8806f1485",
              "last_collected_at": "2024-12-17T06:32:56.922Z"
          },
          "region_code": "ap-northeast-2",
          "domain_id": "domain-1111111111",
          "workspace_id": "workspace-1111111111",
          "project_id": "project-11111111111",
          "created_at": "2024-12-17T06:32:56.922Z",
          "updated_at": "2024-12-17T06:32:56.922Z"
      }
  ] ... ,
  "total_count": 23
}

2. View Information of a Resource (Cloud Service) from the Output Resource List

Request

curl -X 'POST' \
  'https://{Base URL}/inventory/cloud-service/get' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_secret}'\
  -d '{
	  "cloud_service_id": "cloud-svc-11111111111111"
	}'

Response

{
    "cloud_service_id": "cloud-svc-11111111111111",
    "name": "service-bastion",
    "state": "ACTIVE",
    "ip_addresses": [
        "10.0.138.84"
    ],
    "account": "11111111111",
    "instance_type": "t3.micro",
    "cloud_service_type": "Instance",
    "cloud_service_group": "EC2",
    "provider": "aws",
    "data": {
        "os": {
            "os_distro": "linux",
            "os_arch": "x86_64",
            "os_type": "LINUX",
            "details": "Linux/UNIX"
        },
        "aws": {
            "ami_id": "ami-1111111111111111",
            "ami_launch_index": 0.0,
            "kernel_id": null,
            "monitoring_state": "disabled",
            "ebs_optimized": true,
            "ena_support": true,
            "hypervisor": "xen",
            "placement": {
                "GroupName": "",
                "Tenancy": "default",
                "AvailabilityZone": "ap-northeast-2a"
            },
            "iam_instance_profile": {
                "Arn": "arn:aws:iam::11111111111:instance-profile/ems-ec2-eks-bastion-role",
                "Id": "AAAAAAAAAAAAAAAAAAAAAAA"
            },
            "root_volume_type": "gp3"
        },
        "hardware": {
            "core": 2.0,
            "memory": 1.0
        },
        "compute": {
            "keypair": "",
            "az": "ap-northeast-2a",
            "instance_state": "STOPPED",
            "instance_type": "t3.micro",
            "launched_at": "2023-11-09T05:58:59",
            "instance_id": "i-0322e4fe54dfa9f0f",
            "instance_name": "obsv-service-bastion",
            "security_groups": [
                {
                    "name": "bastion-sg-01",
                    "id": "sg-1111111111",
                    "display": "bastion-sg-01 (sg-1111111111)"
                }
            ],
            "image": "ec2-20231107-final",
            "account": "11111111111"
        }
    },
    "reference": {
        "resource_id": "i-111111111111",
        "external_link": "https://ap-northeast-2.console.aws.amazon.com/ec2/v2/home?region=ap-northeast-2#Instances:instanceId=i-111111111111"
    },
    "tags": {
        "aws": {
            "Name": "service-bastion"
        }
    },
    "tag_keys": {
        "aws": [
            "Name"
        ]
    },
    "collection_info": {
        "service_account_id": "sa-11111113c43",
        "secret_id": "secret-aaa88e9e1110",
        "collector_id": "collector-afc8806f1485",
        "last_collected_at": "2024-12-17T06:32:56.922Z"
    },
    "region_code": "ap-northeast-2",
    "domain_id": "domain-1111111111",
    "workspace_id": "workspace-1111111111",
    "project_id": "project-11111111111",
    "created_at": "2024-12-17T06:32:56.922Z",
    "updated_at": "2024-12-17T06:32:56.922Z"
}

3. View List of Specific Managed Tag Related EC2 Resources

Request

curl -X 'POST' \
  'https://{Base URL}/inventory/cloud-service/list' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {client_secret}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query":
    {
        "page":
        {
            "start": 1,
            "limit": 20
        },
        "filter":
        [
            {
                "k": "provider",
                "v": "aws",
                "o": "eq"
            },
            {
                "k": "cloud_service_group",
                "v": "EC2",
                "o": "eq"
            },
            {
                "k": "tags.aws.Created_by",
                "v": "wonny",
                "o": "eq"
            }
        ]
    }
}'

Response

{
    "results":
    [
        {
            "cloud_service_id": "cloud-svc-22222222",
            "name": "spaceone-instance",
            "state": "ACTIVE",
            "account": "111111111111",
            "provider": "aws",
            "data":
            {
                "compute":
                {
                    "az": "ap-northeast-2b",
                    "instance_type": "t3.xlarge",
                    "instance_state": "RUNNING"
                },
                "os":
                {
                    "os_distro": "amazonlinux"
                },
                "hardware":
                {
                    "core": 4.0,
                    "memory": 16.0
                },
                "primary_ip_address": ""
            },
            "reference":
            {
                "resource_id": "i-0111111111",
                "external_link": ""
            },
            "tags":
            {
                "aws":
                {
                   
                    "Created_by": "wonny"
                }
            },
            "tag_keys":
            {},
            "collection_info":
            {},
            "region_code": "ap-northeast-2",
            "project_id": "project-111111111",
            "updated_at": "2025-01-01T09:56:56.256Z"
        }
    ],
    ...
    "total_count": 2
}

4. View List of SecurityGroup (SG) Used by EC2

Request

curl -X 'POST' \
  'https://{Base URL}/inventory/cloud-service/list' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {client_secret}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query":
    {
        "page":
        {
            "start": 1,
            "limit": 20
        },
        "only":
        [
            "name",
            "state",
            "data.instances"
        ],
        "filter":
        [
            {
                "k": "provider",
                "v": "aws",
                "o": "eq"
            },
            {
                "k": "cloud_service_group",
                "v": "EC2",
                "o": "eq"
            },
            {
                "k": "cloud_service_type",
                "v": "SecurityGroup",
                "o": "eq"
            },
            {
            	"k": "data.instances",
            	"v": [null, []],
            	"o": "not_in"
            }
        ]
    }
}'

Response

{
  "results": [
    {
      "name": "ems-eks-bastion-sg-01",
      "state": "ACTIVE",
      "data": {
        "instances": [
          {
            "SubnetId": "subnet-111111111111",
            "PrivateIpAddress": "10.0.0.0",
            "PrivateDnsName": "ip-10-0-0-0.ap-northeast-1.compute.internal",
            "VpcId": "vpc-11111111111",
            "Tags": [
              {
                "Key": "Name"
              }
            ],
            "Architecture": "x86_64",
            "InstanceId": "i-11111111111",
            "PublicDnsName": "amazonaws.com",
            "State": {
              "Name": "running"
            },
            "PublicIpAddress": "",
            "instance_name": "spaceone-instance",
            "SecurityGroups": [
              {
                "GroupName": "sg-01",
                "GroupId": "sg-11111111111"
              }
            ]
          }
        ]
      },
      "tags": {},
      "tag_keys": {},
      "collection_info": {}
    }
  ],
  ...
  "total_count": 10
}

Cost (Cost Analysis) View Scenario

1. View Data Source

Request

curl -X 'POST' \
  'https://{Base URL}/cost-analysis/data-source/list' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_secret}'\
  -d '{
  "query": {}
}'

Response

{
  "results": [
    {
      "data_source_id": "string",
      "name": "string",
      "state": "string",
      "data_source_type": "string",
      "permissions": {},
      "provider": "string",
      "secret_type": "string",
      "secret_filter": {
        "state": "string",
        "secrets": [
          "string"
        ],
        "service_accounts": [
          "string"
        ],
        "schemas": [
          "string"
        ]
      },
      ...
      ...
      "data_source_account_count": 0,
      "connected_workspace_count": 0,
      "resource_group": "string",
      "domain_id": "string",
      "workspace_id": "string",
      "created_at": "string",
      "updated_at": "string",
      "last_synchronized_at": "string"
    }
  ],
  "total_count": 4
}

2. View Cost Information Collected by Specific Data Source on Specific Date

Request

curl -X 'POST' \
  'https://<Base URL>/cost-analysis/cost/list' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {client_secret}'\
  -d '{
  "query": {
    "filter": [
      {
        "key": "data_source_id",
        "value": "ds-a8cac8e9c7c8",
        "operator": "eq"
      },
      {
	      "key": "billed_date",
	      "value": "2024-12-16",
	      "operator": "eq"
      }
    ]
  }
}'

Response

{
  "results": [
    {
      "cost_id": "string",
      "cost": "string",
      "usage_quantity": "string",
      "usage_unit": "string",
      "provider": "string",
      "region_code": "string",
      "region_key": "string",
      "product": "string",
      "usage_type": "string",
      "resource": "string",
      "tags": {},
      "additional_info": {},
      "data": {},
      "domain_id": "string",
      "workspace_id": "string",
      "project_id": "string",
      "service_account_id": "string",
      "data_source_id": "string",
      "account_id": "string",
      "billed_year": "string",
      "billed_month": "string",
      "billed_date": "string"
    },
    ...
    ...
  ],
  "total_count": 356
}

Installing SpaceONE