NAVER Cloud Platform API

Overview

The application program interface (API) that supports the use of services and solutions provided by NAVER Cloud Platform is called NAVER Cloud Platform API.

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.

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

• 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.
  • Caution: The x-ncp-apigw-timestamp value of the request header and the timestamp of StringToSign must be the same value.

• 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

• For responses to service API calls, please refer to the API guide of each service.

Handle error

• For error codes for service API calls, please refer to the API guide of each service.

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)
  

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

Error Codes

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.

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 2 versions are available: Ncloud APIs V1, and Ncloud APIs V2
We recommend you to use the Ncloud APIs V2, which comes with enhanced usability; the Ncloud APIs V1 will be deprecated with prior notice.

• 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 services require an API key, please refer to the API specifications of each service.

Authentication methods

• 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

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

Ncloud APIs deprecation schedule

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