Common

Overview

We provide an Application Programming Interface (API) that supports the use of infrastructure/solution products provided by Samsung Cloud Platform.

This guide provides a brief description of the Samsung Cloud Platform Open API and how to call API.

The API is provided as a RESTful API, and it responds in JSON format.

Depending on the API, you can enter parameter values and register, modify, delete, and retrieve.

It is used through the HTTP POST/GET/PUT/DELETE method call.

When the call fails, it returns an error code and message.

API Versioning

OpenAPI supports Micro version-style API versioning. You can call the endpoint API of each product to check the product’s API version.

By setting the Scp-Api-Version header according to the supported version, you can invoke the corresponding version of the API.

If the header is not set, the latest current version supported by the product will be called. The request/response format may change depending on the version invoked, especially after version updates.

API Veris Status List

Example Version Information API Call

https://iam.s.samsungsdscloud.com/

Example Version Information API response

{
  "versions": [
    {
      "id": "v1.0",
      "links": [
        {
          "href": "http://iam.s.samsungsdscloud.com/v1",
          "rel": "self"
        }
      ],
      "not_before": "2026-02-23",
      "status": "CURRENT"
    }
  ]
}

Samsung Cloud Platform Open API Call Procedure

The SCP OpenAPI URL must be modified according to the operating environment and region. Please refer to the table below to find the relevant operating environment and region information.

Get Your Application Credential

To use the Open API function of Samsung Cloud Platform, you need to issue an access key.

Access key issue can be checked in [My Menu] > [My Info] > [Access Key Management] in the console of Samsung Cloud Platform.

API access key pairs with Access Secret Key. The access key is used to generate authentication tokens.

1. Log in to the Samsung Cloud Platform website.
2. When accessing the My Menu > My Info > Access Key Management menu, click the Create Access Key button.
3. After creating the period and usage, click OK to generate an authentication key.
4. Check the issued Access Key and Access Secret Key from the access key list.
   • Access Secret Key can be found on the Authentication Key Details page.

Security Token Service (Optional)

Security Token Service allow users to access the system with authentication information that is only valid for a specific period. These credentials are typically used for the following purposes:

• Enhanced Security: To minimize damage in case of a leak of long-term credentials (e.g., API keys, passwords).
• Delegated Authority: To temporarily grant limited permissions to external users or systems.
• Automatic Expiration: Credentials expire automatically after a set time, simplifying management

Components

Security Token Service includes the following information:

1. Access Key: An identifier for authentication.
2. Secret Key: Used to create an encrypted authentication signature.
3. Session Token: A token for session identification and validation.

Creating Security Token Service

To use the Samsung Cloud Platform’s temporary security credentials feature, you must create a role.

Role creation can be managed in the Samsung Cloud Platform Console under [My Menu] > [My Info] > [Role]

• Principal

  • When creating a role, you must define the principal that can assume the role.
  • The principal can be an account, user SRN, identity provider, etc., which is authorized to assume the role.

• Policy

  • You must set a permissions policy that defines what actions the role can perform.
  • The policy should adhere to the Principle of Least Privilege, granting only the necessary permissions.

1. Log in to the Samsung Cloud Platform Console.
2. Navigate to My Menu > My Info > Role and click the Create Role button.
3. Enter a role name and select the maximum session duration to set the validity period for assuming the role.
4. Under Attach principal, click the Classification button to set the trust entity. You can click the Add button to set multiple trust entities.
5. Under Attach Policy, find the desired policy from the policy list and click the checkbox on the left to select it.
6. Click the Complete button to finish creating the role.

After this, you must generate a token for the role. This is done by executing the assume-role API, which returns an Access Key, Secret Key, and Session Token.

assume-role Usage Guide : assume-role usage

Call API

AUTH PARAMS

Header Description

Scp-Accesskey   : Access Key issued by Samsung Cloud Platform Portal or Temporary Access key from Security Token Service
Scp-Signature   : Signatures encrypted with an Access Secret Key that maps the call API request to the Access Key. HMAC encryption algorithm uses HmacSHA256
Scp-Timestamp   : defines the elapsed time from 00:00:00 Agreement World Time (UTC) on January 1, 1970, in milliseconds.
Scp-ClientType  : Client Type
Scp-Session-Token (Optional) : Session token from Security Token Service

LANGUAGE PARAMS

The language used to run the Open API must be set to Accept-Language in the request header.

Header Description

Accept-Languages : Set the language to be used when executing the API (using English when not entered)
                  Korean    : ko-KR
                  English   : en-US
                  
Scp-Api-Version : A header for microversion must be entered when calling openapi.
                  If there is no corresponding information in the header, the latest current version supported by the current product will be called
                  The req/res may change depending on the version you are calling.

Create Signature

• It generates a string to sign from the request, encrypts it with the HmacSHA256 algorithm with the Access Secret Key, and encodes it into Base64.
• Use this value as a Scp-Signature.
• The generated Signature is valid for 15 minutes.

Create Signature Sample Code (Java)

public static String makeHmacSignature(String method,
                                       String url,
                                       String timestamp,
                                       String accessKey,
                                       String accessSecretKey,
                                       String clientType) {
 
    String body = method + url + timestamp + accessKey + clientType;
 
    String encodeBase64Str;
 
    try {
        byte[] message = body.getBytes("UTF-8");
        byte[] secretKey = accessSecretKey.getBytes("UTF-8");
 
        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey, "HmacSHA256");
        mac.init(secretKeySpec);
        byte[] hmacSha256 = mac.doFinal(message);
        encodeBase64Str = Base64.getEncoder().encodeToString(hmacSha256);
    } catch (Exception e) {
        throw new RuntimeException("Failed to calculate hmac-sha256", e);
    }
 
    return encodeBase64Str;
}

Create Signature Sample Code (JavaScript)

<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/rollups/hmac-sha256.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/components/enc-base64-min.js"></script>
<script type="text/javascript">
function makeSignature() {
    var method = "GET"; // Method
    var url = "{url}"; // url
    var timestamp = Date.now(); // timestamp
    var accessKey = "{accessKey}"; // access key
    var secretKey = "{secretKey}"; // secret key
    var clientType= "{clientType}"; // client type
 
    url = encodeURI(url); // Handles Hangul and Special Characters
 
    var message = method + url + timestamp + accessKey + clientType;
 
    var hash = CryptoJS.HmacSHA256(message, secretKey);
    return CryptoJS.enc.Base64.stringify(hash);
}
</script>

Open API Call Example

Curl

curl -i -X GET
-H "Scp-Accesskey:2sd2gg=2agbdSD26svcD"
-H "Scp-Signature:fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef="
-H "Scp-Timestamp:1605290625682"
-H "Scp-ClientType:Openapi"
-H "Accept-Language:en-US"
-H "Scp-Api-Version: sample 1.0"
(Optional) -H "Scp-Session-Token: AAEKCWtyLXdlc3QtMRICdjEazgUKywUEeJqax6lq904t..."
'https://support.{env}.samsungsdscloud.com/v1/notices'

Python

import requests

url = "https://support.{env}.samsungsdscloud.com/v1/notices"
payload = {}
headers = {
  'Scp-Accesskey': '2sd2gg=2agbdSD26svcD',
  'Scp-Signature': 'fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef=',
  'Scp-Timestamp': '1605290625682',
  'Scp-ClientType': 'Openapi',
  'Accept-Language': 'en-US',
  'Scp-Api-Version': 'sample 1.0',
  # (Optional)
  'Scp-Session-Token': 'AAEKCWtyLXdlc3QtMRICdjEazgUKywUEeJqax6lq904t...'
}

response = requests.request("GET", url, headers=headers, data=payload)

if response.status_code == 200:
    contents = response.text
    return contents
else:
    raise Exception(f"Failed to GET API: {response.status_code}, {response.text}")

Java

String apiUrl = "https://support.{env}.samsungsdscloud.com/v1/notices";
String language = "ko-KR";
String accessKey = "2sd2gg=2agbdSD26svcD"
String signature = "fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef="
String timestamp = "1605290625682"
String clientType = "Openapi"
String apiVersion = "sample 1.0"
String sessionToken = "AAEKCWtyLXdlc3QtMRICdjEazgUKywUEeJqax6lq904t..."

public static String getAPI(String token, String apiUrl, String language) throws IOException {
        CloseableHttpClient httpClient = HttpClients.createDefault();
        HttpGet getRequest = new HttpGet(apiUrl);
        getRequest.addHeader("Scp-Accesskey", accessKey);
        getRequest.addHeader("Scp-Signature", signature);
        getRequest.addHeader("Scp-Timestamp", timestamp);
        getRequest.addHeader("Scp-ClientType", clientType);
        getRequest.addHeader("Accept-Language", language);
        getRequest.addHeader("Scp-Api-Version", apiVersion);
        // (Optional)
        getRequest.addHeader("Scp-Session-Token", sessionToken);

        HttpResponse response = httpClient.execute(getRequest);
        int statusCode = response.getStatusLine().getStatusCode();

        if (statusCode == 200) {
            String responseBody = EntityUtils.toString(response.getEntity());
            httpClient.close();
            return responseBody;
        } else {
            String responseBody = EntityUtils.toString(response.getEntity());
            httpClient.close();
            throw new RuntimeException("Failed to Request: " + statusCode + ", " + responseBody);
        }
    }

Response

* *For responses to product API calls, refer to the respective product guide(API Reference).

Common Error Codes

Common Error Response

{
    "errors": [
        {
            "request_id": "req-aca5442b21eb46d89e4740f529ecbc6e",
            "global_request_id": "req-c79a747b-a50e-434d-a6f2-90aa7d06c1ea",
            "code": "extension.api.server-error",
            "status": 404,
            "title": "Not Found",
            "detail": "No Notice found with ID d34f74a2dfc244e0bba141fd667475ad",
            "related_resources": [],
            "links": [],
            "response": {}
        }
    ]
}

Common Error Status Codes