Ncloud API

Available in Classic and VPC

NAVER Cloud Platform APIs are provided in the RESTful API method and respond in JSON and XML formats. You can enter action-specific parameters to register, modify, delete, and search them. You can also utilize them to run services and automate operation tools. Methods are called using the HTTP method, and an error code and message are returned if the call fails. Ncloud APIs include all APIs of NAVER Cloud Platform except for compatible APIs and integration APIs.

API authentication key

The NAVER Cloud Platform APIs issue a pair of user identification tools, API authentication keys, consisting of an Access key and a Secret key, to each account so that only authorized users can call them. This is used as a parameter that is passed when authenticating to call an API. Therefore, to use NAVER Cloud Platform APIs, you must first create an authentication key.
The creation and management of authentication keys is done through NAVER Cloud Platform's portal. The following describes how to create and manage authentication keys in the NAVER Cloud Platform portal.

1. Log in to the NAVER Cloud Platform portal.
2. Click the My Page > Manage account > Manage authentication key menus, in that order.
3. Check the access key ID and secret key provided by default in Manage API authentication key.
4. Proceed with the necessary task.
   • Issue additional API authentication key
     • Click the [Create new API authentication key] button.
   • Disable API authentication key
     • Click the [Disable] button.
     • Click the [Use] button to re-enable the disabled authentication key.
   • Delete API authentication key
     • Click the [Delete] button.
     • Only disabled authentication keys can be deleted.

Common API settings

The following describes commonly used request and response formats in Ncloud APIs.

Request

The following describes the common request format.

API URL

See the API guide for each service for the request API URL.

Create signature

A signature is a value that is entered in the common request header field x-ncp-apigw-signature-v2. It is a signature value created by encrypting the request information with the API authentication key (SecretKey mapped to AccessKey) and then encoding it in Base64. The HMAC encryption algorithm (HmacSHA256) is used for encryption.
The example code for each language that creates a signature is as follows.

public String makeSignature() {
	String space = " ";					// one space
	String newLine = "\n";					// new line
	String method = "GET";					// method
	String url = "/photos/puppy.jpg?query1=&query2";	// url (include query string)
	String timestamp = "{timestamp}";			// current timestamp (epoch)
	String accessKey = "{accessKey}";			// access key id (from portal or Sub Account)
	String secretKey = "{secretKey}";

	String message = new StringBuilder()
		.append(method)
		.append(space)
		.append(url)
		.append(newLine)
		.append(timestamp)
		.append(newLine)
		.append(accessKey)
		.toString();

	SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256");
	Mac mac = Mac.getInstance("HmacSHA256");
	mac.init(signingKey);

	byte[] rawHmac = mac.doFinal(message.getBytes("UTF-8"));
	String encodeBase64String = Base64.encodeBase64String(rawHmac);

  return encodeBase64String;
}

/*
https://code.google.com/archive/p/crypto-js/
https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/crypto-js/CryptoJS%20v3.1.2.zip
*/

/*
CryptoJS v3.1.2
code.google.com/p/crypto-js
(c) 2009-2013 by Jeff Mott. All rights reserved.
code.google.com/p/crypto-js/wiki/License
*/



function makeSignature() {
	var space = " ";				// one space
	var newLine = "\n";				// new line
	var method = "GET";				// method
	var url = "/photos/puppy.jpg?query1=&query2";	// url (include query string)
	var timestamp = "{timestamp}";			// current timestamp (epoch)
	var accessKey = "{accessKey}";			// access key id (from portal or Sub Account)
	var secretKey = "{secretKey}";			// secret key (from portal or Sub Account)

	var hmac = CryptoJS.algo.HMAC.create(CryptoJS.algo.SHA256, secretKey);
	hmac.update(method);
	hmac.update(space);
	hmac.update(url);
	hmac.update(newLine);
	hmac.update(timestamp);
	hmac.update(newLine);
	hmac.update(accessKey);

	var hash = hmac.finalize();

	return hash.toString(CryptoJS.enc.Base64);
}

import sys
import os
import hashlib
import hmac
import base64
import requests
import time

def	make_signature():
	timestamp = int(time.time() * 1000)
	timestamp = str(timestamp)

	access_key = "{accessKey}"				# access key id (from portal or Sub Account)
	secret_key = "{secretKey}"				# secret key (from portal or Sub Account)
	secret_key = bytes(secret_key, 'UTF-8')

	method = "GET"
	uri = "/photos/puppy.jpg?query1=&query2"

	message = method + " " + uri + "\n" + timestamp + "\n"
	+ access_key
	message = bytes(message, 'UTF-8')
	signingKey = base64.b64encode(hmac.new(secret_key, message, digestmod=hashlib.sha256).digest())
	return signingKey

function makeSignature() {
	nl=$'\\n'

	TIMESTAMP=$(echo $(($(date +%s%N)/1000000)))
	ACCESSKEY="{accessKey}"				# access key id (from portal or Sub Account)
	SECRETKEY="{secretKey}"				# secret key (from portal or Sub Account)

	METHOD="GET"
	URI="/photos/puppy.jpg?query1=&query2"

	SIG="$METHOD"' '"$URI"${nl}
	SIG+="$TIMESTAMP"${nl}
	SIG+="$ACCESSKEY"

	SIGNATURE=$(echo -n -e "$SIG"|iconv -t utf8 |openssl dgst -sha256 -hmac $SECRETKEY -binary|openssl enc -base64)
}

Request headers

The common header of the NAVER Cloud Platform API includes fields related to authentication. The following describes the request headers.

Request example

The following is a sample request using the authentication key and common header.

curl --location --request GET 'https://example.apigw.ntruss.com/photos/puppy.jpg?query1=&query2' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \

Response

The following describes the common response format.

Response status codes

The following describes the response status codes.

Response example

The response example is as follows:

• Succeeded(Content-type: application/json)

  {
    "status": {
      "code": "20000",
      "message": "OK"
    },
    "result": {...}
  }
  

• Succeeded(Content-type: application/xml)

  <Message>
     <status>
         <code>20000</code>
         <message>OK</message>
     </status>
     <result> ... </result>
  </Message>
  

• Failure(Content-type: application/json)

  {
   "error":{
      "errorCode":"210",
      "message":"Permission Denied"
    }
   }
  

• Failure(Content-type: application/xml)

  <?xml version='1.0' encoding='UTF-8' ?>
  <Message>
      <error>
       <errorCode>210</errorCode>
       <message>Permission Denied</message>
   </error>
  </Message>
  

Set API security

An API can cause serious security issues if the authentication key is leaked to a third party, as the resource can be arbitrarily changed or viewed. Therefore, proper preparation and response are required.

Reissue API authentication key

If you are not using the API authentication key or suspect that it has been stolen, please disable or delete the issued authentication key and reissue it.

Use sub account authentication key

You can issue an API authentication key from a sub account, not the main account, which has all the permissions, to call the API, and you can also periodically replace it in case of a key leak. Sub accounts can be used only after being granted the appropriate permissions, and APIs can be used more securely because not only IP ranges but also VPCs can be specified as API access sources.
Sub accounts are created in the NAVER Cloud Platform's Sub Account service. See the Sub Account User Guide for how to create a sub account and API authentication key.

Set access restriction to API

To prevent API Gateway access from unauthorized locations, you can set it to be available only in specific IP ranges. The following describes how to set API access to be available only in specific IP ranges.

1. Log in to the NAVER Cloud Platform portal.
2. Click the My Page > Manage account > Manage authentication key menus, in that order.
3. Enter the IP range to allow access in IP Address in Set API access restrictions
   • Enter by referring to CIDR notation.
   • The 0.0.0.0 to 32 range can't be entered for security reasons.
   • All connections are allowed unless otherwise registered.
4. Click the [Save] button.
   • Click the [Add] button to add an IP range to allow access.

CIDR notation

An IP address is expressed in the format 192.168.0.1 to 192.168.0.255 to indicate the IP range to allow access. NAVER Cloud Platform also supports the method of entering using the Classless Inter-Domain Routing (CIDR) notation, which is mainly used when managing networks.

CIDR is one of the methods for denoting a range of consecutive IP addresses. The CIDR notation divides IP addresses into Net ID (Network ID) and Host ID, and groups the IP bands (Host ID categories) that belong to the Net ID to express them. This is also known as Address Aggregation/Supernetting.

The IP address that is commonly used is made up of four octets as follows.

The CIDR notation is used to indicate an IP address consisting of four octets and a range value after a slash (/). The range value can be used from 0 to 32, i.e. up to 32 bits. In CIDR notation, this can be understood as meaning that the number of bits that can come after the range value can be used.
Therefore, the IP range is calculated as the range from the four-octet value represented by the IP address to the number of bits that can come after the range value. At this time, the number of bits from the 4-octet value of the IP address to the range value is considered as a fixed area, the Net ID, and the remaining bits are calculated as the Host ID range that can be used.

The number of IP addresses of the host by the range value is as follows.

Supported APIs and SDKs

This section provides information on APIs and SDKs supported by the NAVER Cloud Platform.

API

See the API guide for each service for the list of supported APIs by service.

SDK

The list of SDKs supported by service and the download links are as follows.