NAVER CLOUD PLATFORM API

Overview

NAVER CLOUD PLATFORM provides a set of application programming interfaces (APIs) which enables you to use infrastructure and solution products.

This page describes what NAVER CLOUD PLATFORM APIs are and how to make an API request.
The Ncloud APIs are RESTful, using HTTP GET and POST methods, and the response format is XML and JSON. You can register, modify, delete, and get data by specifying required parameters, in order to run services and automate operation tools.

If an API request fails, it returns an error code and message.

How to make an API request

Follow the steps below to make an API request.
1. Create authentication key
2. Make API request
3. Handle response
4. Handle error

Create authentication key

Once an NAVER CLOUD PLATFORM account is created, one NAVER CLOUD PLATFORM API authentication key is issued by default. Go to My Page > Manage Account > Manage Auth Key in NAVER CLOUD PLATFORM to get the authentication key. Apart from the one automatically issued when an account is created, you can create one more authentication key. That is, an account can have up to two authentication keys.

info
You can disable or delete your authentication key if you don’t need it anymore.


An API authentication key consists of a pair of Access Key ID and Secret Key. They are passed as a parameter to authenticate an API.

  1. Log in to NAVER CLOUD PLATFORM.
  2. Go to My Page > Manage Account > Manage Auth Key, and click Create a New API Authentication Key.
    • You can use a previously created authentication key, if there is any.
  3. Check your Access Key ID and Secret Key in Manage Auth Key.

Make API request

AUTHPARAMS

Header Description
x-ncp-apigw-timestamp It is the number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC.
* If the time difference with the API Gateway server is more than 5 minutes, the request is considered invalid.
x-ncp-iam-access-key * Access Key ID issued from the NAVER CLOUD PLATFORM Portal or Sub Account.
x-ncp-apigw-signature-v2 * Signature used to encrypt the body of the example with the “secret key” that maps with the “access key.”
* The HMAC encryption algorithm is HMAC SHA256.
  • AUTHPARAMS request example

    curl -i -X GET \
    -H "x-ncp-apigw-timestamp:1505290625682" \
    -H "x-ncp-iam-access-key:D78BB444D6D3C84CA38A" \
    -H "x-ncp-apigw-signature-v1:WTPItrmMIfLUk/UyUIyoQbA/z5hq9o3G8eQMolUzTEo=" \
    'https://example.apigw.ntruss.com/photos/puppy.jpg?query1=&query2'
    
  • Create a signature

    • Add a new line with \n.
    • Create a StringToSign appropriate for your request, encrypt it with your secret key and the HMACSHA256 algorithm and encode it with Base64.
    • Use this value as x-ncp-apigw-signature-v2.
Request StringToSign
GET /photos/puppy.jpg?query1=&query2
x-ncp-apigw-timestamp={timestamp}
x-ncp-iam-access-key={accesskey}
x-ncp-apigw-signature-v1={signature}
GET /photos/puppy.jpg?query1=&query2
{timeStamp}
{accessKey}
  • Request example
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
*/
<script type="text/javascript" src="./CryptoJS/rollups/hmac-sha256.js"></script>
<script type="text/javascript" src="./CryptoJS/components/enc-base64.js"></script>

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+="$APIKEY"${nl}
	SIG+="$ACCESSKEY"

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

Handle response

  • Check the response format for each API and handle responses accordingly.

Handle error

  • Check the response format for each API and handle responses accordingly.

API error examples

  • For user errors: HTTP Response Code = 400
  <responseError>
  	<returnCode>900</returnCode>
  	<returnMessage>
  	Required field is not specifie4. location : serverImageProductCode.
  	</returnMessage>
  </responseError>
  • For authentication errors: HTTP Response Code = 401
  <responseError>
  	<returnCode>801</returnCode>
  	<returnMessage>Signature is invalided</returnMessage>
  </responseError>

Common Error Code

  • When responseFormatType=xml is set
<?xml version='1.0' encoding='UTF-8' ?>
<Message>
    <error>
        <errorCode>210</errorCode>
        <message>Permission Denied</message>
    </error>
</Message>
  • When responseFormatType=json is set (default)
    json { "error":{ "errorCode":"210", "message":"Permission Denied" } }

Error Codes

HTTP status code Error code Error message Description
400 100 Bad Request Exception Request error in protocol (https) or encoding (UTF-8).
401 200 Authentication Failed Authentication failed.
401 210 Permission Denied No permissions.
404 300 Not Found Exception No permissions.
429 400 Quota Exceeded Quota exceeded.
429 410 Throttle Limited Rate exceeded.
429 420 Rate Limited Rate exceeded.
413 430 Request Entity Too Large Request entity size exceeded.
503 500 Endpoint Error Endpoint connection error
504 510 Endpoint Timeout Endpoint connection timeout.
500 900 Unexpected Error Exception unhandled.

Supported APIs and SDKs

NAVER CLOUD PLATFORM enables you to control various services such as Server, Load Balancer, Auto Scaling, Monitoring, Security, GeoLocation and Hash Filter with APIs. The APIs are RESTful, and their response format is XML and JSON. You can register, modify, delete, and get data by specifying required parameters, in order to run services and automate operation tools.

Product API SDK
Server Server API ncloud_server.zip
Load Balancer Load Balancer API ncloud_loadbalancer.zip
Auto Scaling Auto Scaling API ncloud_autoscaling.zip
Monitoring Monitoring API ncloud_monitoring.zip
Security Security API ncloud_security.zip
GeoLocation GeoLocation API ncloud_geolocation.zip
CDN CDN API ncloud_cdn.zip
    Cloud DB Cloud DB API ncloud_clouddb_v2.zip
    Cloud Outbound Mailer Cloud Outbound Mailer API ncloud_outboundmailer.zip

Ncloud APIs Release Note

NAVER CLOUD PLATFORM’s Ncloud APIs have been improved since the first release.

Available versions of the Ncloud APIs

Currently, the following 3 versions are available: Ncloud APIs Old, Ncloud APIs V1, and Ncloud APIs V2
We recommend you to use the Ncloud APIs V2, which comes with enhanced usability; the Ncloud APIs Old and the Ncloud APIs V1 will be deprecated with prior notice.

  • Ncloud APIs Old

    This version of APIs was provided in the early stage of NAVER CLOUD PLATFORM, using the domain that starts with https://api.ncloud.com/ This version uses the OAuth authentication method.
  • Ncloud APIs V1

    This version of APIs is available via the new API Gateway that supports enhanced API management, using the domain that starts with https://ncloud.apigw.ntruss.com/. The Ncloud APIs V1 requires an API key issued by the API Gateway for authentication.

    As the Ncloud APIs V1 requires an API key issued by the API Gateway, you should apply for the API Gateway service. (Note that you will not be charged for the API Gateway service since you only get an API key.)

  • Ncloud APIs V2

    The operations and how to make API requests in the Ncloud APIs V2 are the same as those in the Ncloud APIs V1, except that the V2 does not require an API key. Therefore, you do not need to apply for API Gateway.

    Since some products require an API key, please refer to the API specifications of each product.

Authentication methods

  1. OAuth authentication method

    • This method is used by the Ncloud APIs Old, where a separate system only allows those who have encrypted authentication tokens to access resources, without storing their login information.
  2. API key authentication method

    • This method requires an API key for each account for authentication. Go to API Gateway > API Keys in NAVER CLOUD PLATFORM’s console and click Create API Key to get an API key.

    • For the Ncloud APIs V1, you must include your API key in the authorization and request headers to make an API request.

    • For the Ncloud APIs V2, you do not need to include your API key in the authorization or request header to make an API request.

Ncloud API documentations

Product Ncloud APIs OLD: (OAuth authentication) Ncloud APIs V1: (API Key authentication) Ncloud APIs V2: (No API Key authentication)
Server Go to documentation Go to documentation Server API
Load Balancer Go to documentation Go to documentation Load Balancer API
Auto Scaling Go to documentation Go to documentation Auto Scaling API
Monitoring Go to documentation Go to documentation Monitoring API
Security Go to documentation Go to documentation Security API
GeoLocation Go to documentation Go to documentation GeoLocation API
CDN Go to documentation Go to documentation CDN API
Global CDN Go to documentation Go to documentation CDN API
Cloud DB N/A Go to documentation Cloud DB API
Cloud Outbound Mailer N/A Go to documentation Cloud Outbound Mailer API

(Since some products require an API key, please refer to the API specifications of each product.)

Ncloud APIs deprecation schedule

  • The Ncloud APIs V1 will be deprecated as of Dec. 31, 2019, and will no longer be available after that.
  • The Ncloud APIs Old will be deprecated as of Jun. 30, 2019, and will no longer be available after that.