33
NTT DOCOMO Confidential Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved 1 Common Reference for docomo Developer support APIs Version 2.0.0 March 17, 2014 NTT DOCOMO, Inc.

Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

  • Upload
    others

  • View
    7

  • Download
    0

Embed Size (px)

Citation preview

Page 1: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

1

Common Reference for docomo Developer support APIs

Version 2.0.0

March 17, 2014

NTT DOCOMO, Inc.

Page 2: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

2

Company names, product names and service names mentioned in this document are trademarks or

registered trademarks of corresponding companies.

In this document, copy rights, trademarks and registered trademarks are not specifically indicated.

Revision history

Date Version Revisions

Nov. 11, 2013 1.0.0 First version

March 17, 2014 2.0.0 Added descriptions for the cases where APIs that require user’s

authorization are used.

Page 3: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

3

Contents

1 Introduction....................................................................................................................................1

1.1. About this document ............................................................................................................ 4

2. To use the APIs ............................................................................................................................. 4

2.1. Outline .................................................................................................................................. 4

2.2. To create applications ........................................................................................................... 4

2.2.1. API key ........................................................................................................................ 5

2.2.2. client_id 【Needed when using APIs that require user’s authorization】 ...................... 5

2.2.3. client_secret 【Needed when using APIs that require user’s authorization】................ 5

2.3. To use APIs that require user’s authorization ....................................................................... 6

2.3.1. Outline ......................................................................................................................... 6

2.3.2. Sequence of new acquisition of access tokens ............................................................. 6

2.3.3. Sequence of access token reissuance (Refresh) ........................................................... 7

2.3.4. Setup for usage ............................................................................................................. 7

2.3.5. Notes ............................................................................................................................ 8

3. Authorization end point ................................................................................................................ 8

3.1. Request ................................................................................................................................. 8

3.2. Response (Normal case) ..................................................................................................... 10

3.3. Response (Error case) ........................................................................................................ 10

4. Token end point ........................................................................................................................... 12

4.1. Request ............................................................................................................................... 12

4.2. Response (Normal case) .................................................................................................. 15

4.3. Response (at the time of an error) ...................................................................................... 18

5. Get User ID ................................................................................................................................. 20

5.1. Request ............................................................................................................................... 20

5.2. Response (at a normal time) ............................................................................................... 21

5.3. Response (at the time of an error) ...................................................................................... 23

6. Common References for APIs..................................................................................................... 26

6.1. Request ............................................................................................................................... 26

6.2. Response ............................................................................................................................ 27

6.3. Common Error Codes ........................................................................................................ 28

(Appendix 1) List of scopes ................................................................................................................ 32

Page 4: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

4

1 Introduction

1.1. About this document

This document describes how to use API keys and access tokens needed for using the APIs

provided by docomo Developer support, and corresponding requests and responses. See the

reference per function for details of each API.

Services and programs that use each API must comply with the use policy and guideline

separately specified.

The environment and mechanism to execute APIs is configured based on Authorization Code

Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for

details.

2. To use the APIs

2.1. Outline

In order for programs created by developers (hereafter, clients) to use each API provided by

docomo Developer support, API usage application must be made and API keys, client_id &

client_secret(depends on the API chosen) must be obtained. Details of each item are described

below.

2.2. To create applications

The following information is needed for API usage application. Among them, Callback URL(※)

is the end point to receive authorization codes to use APIs that require user’s authorization(See

Section 2.3) (See Subsection 2.3.2). Because Callback URL is a mandatory item, in case only the

APIs not requiring user authorization are used, dummy values (https://dummy) must be entered.

See API Common Guideline for details of other items.

<Items that must be registered in docomo Developer support>

Application name

Outline of application

Planned service start date

Service icon image

Application type

Page 5: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

5

Callback URL※

Support mail address

Site URL

Further, with the API usage application, the following information can be obtained. Among them,

client_id and client_secret(※) are needed to use APIs that require user’s authorization(See Section

2.3).

<Items that must be obtained from docomo Developer support>

API key

client_id※

client_secret※

Details of each item are described below.

2.2.1. API key

API keys are an information element that must be added to requests to execute APIs and can be

obtained through usage application of docomo Developer support. Please see to it that API keys are

not referenced by outsiders.

Please make sure not to add API keys to requests for the API call for Photo Collection, Data

Storage Box and DOCOMO Phonebook. See the reference per function for each API.

2.2.2. client_id【Needed when using APIs that require user’s authorization】

An ID needed to obtain an authorization code (authorization_code) and can be obtained through

usage application of docomo Developer support.

2.2.3. client_secret 【 Needed when using APIs that require user’s

authorization】

This can be obtained by applying via docomo Developer support’s “Apply for API

Usage” .Access tokens can be obtained with authorization code and client_secret. Please see to it

that client_secret is not referenced by outsiders.

Page 6: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

6

2.3. To use APIs that require user’s authorization

2.3.1. Outline

In order for programs created by developers (hereafter, clients) to execute APIs that require

user’s authorization among the APIs provided by docomo Developer support, the user’s

authorization must be obtained to the effect that the clients will access the user’s resources via the

APIs and that what and how such resources are referenced and operated.

The mechanism to authenticate users and request authorization is prepared by docomo Developer

support and clients can use it. When authorization is obtained from users, the clients can obtain

access tokens from the docomo Developer support system.

In order to execute APIs that require user’s authorization, access tokens must be added to requests

in addition to API keys※

. The docomo Developer support system examines validity of the added

access tokens, and when they are judged valid, it will execute the requests specified by the clients.

(※)Please make sure not to add API keys to requests for APIs for Photo Collection, Data Storage

Box and DOCOMO Phonebook. See the reference per function for each API.

2.3.2. Sequence of new acquisition of access tokens

The following is the sequence for new acquisition of access tokens. The following 2 points require

applications to implement calling of the authentication authorization server:

・Call the authorization end point

・Call the token end point

When the authorization end point is called by using a Callback URL specified at new application

registration, scope and issued client_id as parameters, the docomoID input screen (in case docomo

ID has not been authenticated) and authorization screen are returned. When the user executes

authorization from the screen, the embedded agreement result reception end point calling process is

executed and a Callback URL already registered in docomo Developer support is called. When the

Callback URL is called, an authorization code is given as a request parameter, therefore, by calling

the token end point by using the authorization code, client_id and client_secret, an access token and

refresh token can be obtained.

Page 7: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

7

2.3.3. Sequence of access token reissuance (Refresh)

By calling the token end point by using the refresh token issued at new acquisition, a new access

token can be obtained.

2.3.4. Setup for usage

Photo Collection API, Data Storage Box API, docomo Phonebook API requires processing of start

of cloud usage in advance. Refer to each of the API’s notes for more details.

Apps Authentication

authorization server

Browser Apps (Callback URL) Authentication

authorization server

1. Call the authorization end point

2. If not authenticated yet, docomoID input screen is returned

3. Authenticates docmoID from docomoID input screen

4. Returns the authorization screen

5. User presses authorization button on the authorization screen

6. Returns an authentication code to destination of redirect

7. Redirect

8. Call the token end point

9. Returns a token

1. Call token end point

2. Returns a token

Page 8: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

8

2.3.5. Notes

In the OAuth 2.0 specification, the client_id and authorization codes are allowed to be referenced

by third parties. However, the Authorization Code Grant supported by the docomo Developer

support system does not assume reference of access tokens and client_secret by third parties. If

access tokens are leaked, third parties can pretend as developers and execute the APIs. Further, if

client_id and client_secret are leaked, issuance of access tokens becomes possible, therefore likewise,

third parties can pretend as developers and execute the APIs. For these reasons, please see to it that

access tokens and client_secret are not referenced by third parties.

As for security, please take measures specified in the RFC of OAuth 2.0 specification.

3. Authorization end point

This chapter explains requests and responses regarding access token acquisition in case AP

Is that require user’s authorization are used.

The end point is the authorization end point in the OAuth2.0 specification and accepts aut

horization requests. Please use a browser to access the authorization end point.

Although several response_type are specified in the authorization end point in the OAuth2.

0 specification, the only response_type supported by the system is ‘code’.

3.1. Request

URL https://api.smt.docomo.ne.jp/cgi11d/authorization

HTTP method GET

Query parameter

name

response_type

Description Request type

Mandatory/Optional: Mandatory

Value Fixed to “code”

Query parameter

name

client_id

Description Client ID

Page 9: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

9

Mandatory/Optional: Mandatory

Value Set client_id issued at new application registration

Query parameter

name

redirect_uri

Description Callback URI. URI to which authorization code is notified.

Mandatory/Optional: Mandatory

Value Sets Callback URL specified at new application registration

Query parameter

name

Scope

Description Scopes(English name) corresponding to the ‘API functions to be used’

requested at API usage application.

Multiple scopes can be specified by delimiting with single-byte spaces.

Mandatory/Optional: Mandatory

Value Sets scope names by delimiting with single-byte spaces. ※1

※1 A list of scopes that can be specified is shown in 0.

Query parameter

name

State

Description Specifies parameters to be provided to Callback URL. See RFC of OAuth2.0

for details..

Mandatory/Optional: Optional

Value Character strings of 1~16 characters.

The following is a sample of requests.

GET

/cgi11d/authorization?response_type=code&client_id=w2fi67u8Uk39ETeREkcXgVlMV3GsMcS54

2fdWGp6iAst&redirect_uri=https%3A%2F%2Ftest.com%2Foauth-client%2Fjsp%2Fbackcode.jsp&

scope=name+sex+tel&state=4iU

HTTP/1.1

User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko)

Chrome/33.0.1750.117 Safari/537.36

Host: api.smt.docomo.ne.jp

Page 10: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

10

3.2. Response (Normal case)

A screen is returned as a response in normal cases.

3.3. Response (Error case)

The following is the response specification in case of error.

No Item Content Remarks

1 Status code 302 ※1

2 Content-Type

of Body

-(No Body)

3 Character code

of Body

-(No Body)

4 URL of

Location header

URL specified with redirectURI when

making a request to the authorization end

point

5 Content-Length

of Body

-(No Body)

※1 In the following cases, an error screen is returned with the status code 200.

+ When invalid client_id is specified

+ When specified redirect_uri does not match that registered in advance

+ When redirect_uri is not specified

Page 11: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

11

Table Response parameter

No Item

name

Parameter

type

Parameter

name

Mand

atory

Forma

t

String

length

Usable

characte

r type

Remarks

1 Error

code

Query

string in

Location

header

URL

Error ○ String - - See ‘Table

List of error

codes’ for

details.

2 State Query

string in

Location

header

URL

State - String 1~16 %x20-7

E

State value

specified

when

making a

request.

Table List of error codes

No Error code Meaning Remarks

1 invalid_request Missing required parameters, invalid

parameters, a client secret effective period is

set and the client secret has expired, etc.

2 unsupported_respo

nse_type

Unsupported response_type.

3 invalid_scope Invalid scope value as below:

・scope values are empty (Only single-byte

space is specified)

・The same scope values are specified multiple

times

・Undefined scope values are specified

・scope values not permitted in the requesting

client are specified.

4 server_error Unexpected authorization server error,

5 temporarily_unava

ilable

State where the authorization server cannot be

used temporally.

Page 12: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

12

The following is a sample of responses.

HTTP/1.1 302 Moved Temporarily

Location: https://test.com/oauth-client/jsp/backcode.jsp?error=invalid_request

4. Token end point

This chapter explains requests and responses regarding refresh token acquisition for access

token and access token reissuance (Refresh) in case APIs that require user’s authorization a

re used.

The end point is the token end point in the OAuth2.0 specification and accepts issuance r

equests of access tokens.

Although the access token acquisition method with several grant_type is specified in the

OAuth2.0 specification, the only grant_type supported by the system are ‘authorization_code’

and ‘refresh_token’.

In case of acquisition of a new access token, the grant_type of ‘authorization_code’, and i

n case of reissuance of expired access tokens, the grant_type of ‘refresh_token’ is used. See

corresponding section for details of the Interface.

4.1. Request

URL https://api.smt.docomo.ne.jp/cgi12/token

HTTP method POST

Body の

Content-Type

application/x-www-form-urlencoded;charset=UTF-8

Character code of

Body

UTF-8

Content-Length of

Body

Size of entity body

The following is the request parameter at new acquisition of access tokens.

HTTP header

name

Authorization

Description Basic authentication credential

Mandatory/Optional: Mandatory

Value As the basic authentication scheme, URL encode a client ID and secret

individually, link them with a ‘:’ (Colon), encode with Base64 and specify.

Page 13: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

13

Query parameter

name

grant_type

Description Grant type

Mandatory/Optional: Mandatory

Value Fixed to “authorization_code”

Query parameter

name

Code

Description Authorization code

Mandatory/Optional: Mandatory

Value Specifies issued authorization codes.

Query parameter

name

redirect_uri

Description Callback URL

Mandatory/Optional: Mandatory

Value Set the URI specified at the authorization end point

The following is a request sample at new acquisition of access tokens.

POST /cgi12/token HTTP/1.1

User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko)

Chrome/33.0.1750.117 Safari/537.36

Host: api.smt.docomo.ne.jp

Authorization: Basic ZGowemFpWnBQWEZTY1dVd1NHSlJhazFyVk・・・zM2MxZA==

Content-Type: application/x-www-form-urlencoded;charset=UTF-8

Content-Length: xxx

grant_type=authorization_code&code=S542fdWGpgVl6iAstw2ETfi67ueREkcMV3GsMc8Uk39X&

redirect_uri=https://test.com/oauth-client/jsp/backcode.jsp

The following is the request parameters at access token reissuance (Refresh).

HTTP header

name

Authorization

Description Basic authentication credential

Mandatory/Optional: Mandatory

Page 14: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

14

Value As the basic authentication scheme, URL encode a client ID and secret

individually, link them with a ‘:’ (Colon), encode with Base64 and specify.

Query parameter

name

grant_type

Description Grant type

Mandatory/Optional: Mandatory

Value Fixed to “refresh_token”

Query parameter

name

refresh_token

Description Refresh token

Mandatory/Optional: Mandatory

Value Specifies issued refresh token

Query parameter

name

Scope

Description Specifies scopes corresponding to access token issuance.

Multiple scopes can be specified by delimiting with single-byte spaces.

For an access token before expiration, a scope can be selected and specified

among the scopes permitted by the user. (Scopes cannot be newly added).

If a scope is not specified, an access token with the same scope will be

reissued.

Mandatory/Optional: Optional

Value Sets scope names by delimiting with single-byte spaces.

The following is a sample of request at access token reissuance (Refresh).

POST /cgi12/token HTTP/1.1

User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko)

Chrome/33.0.1750.117 Safari/537.36

Host: api.smt.docomo.ne.jp

Authorization: Basic ZGowemFpWnBQWEZTY1dVd1NHSlJhazFyVk・・・zM2MxZA==

Content-Type: application/x-www-form-urlencoded;charset=UTF-8

Content-Length: xxx

grant_type=refresh_token&refresh_token=p6k3idtlwheeTtFpr6d2cT3RcRIMePmfOjZbmQnRZRrh

Page 15: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

15

4.2. Response (Normal case)

The following is the response specification in normal cases.

No Item Content Remarks

1 Status code 200

2 Content-Type

of Body

application/json;charset=UTF-8

3 Character code

of Body

UTF-8

4 Cache-Control

header

no-store

5 Pragma header no-cache

6 Content-Length

of Body

Size of entity body

Table Response parameter (At new acquisition of access token)

No Item

name

Paramete

r

type

Parameter

name

Ma

nd

ato

ry

Forma

t

Char

acter

lengt

h

Usable

character

type

Remarks

1 Acces

s

token

Body

(JSON)

access_token ○ String 44 %x20-7E Access token.

Used when

accessing APIs.

2 Token

type

Body

(JSON)

token_type ○ String - - Value is fixed

to ”Bearer”

3 Effecti

ve

period

Body

(JSON)

expires_in ○ String - %x30-39 Seconds

indicating the

effective period

of access

tokens.

Page 16: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

16

No Item

name

Paramete

r

type

Parameter

name

Ma

nd

ato

ry

Forma

t

Char

acter

lengt

h

Usable

character

type

Remarks

4 Refres

h

token

Body

(JSON)

refresh_toke

n

- String 44 %x20-7E Refresh token.

Used at

reissuance

(Refresh) of

access tokens.

5 scope Body

(JSON)

scope ○ String 1~

512

Each

scope

value is

%x41-5A

/%x61-7

A

%x30-39

Authorized

scope.

The following is a sample at new acquisition of access tokens.

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

Cache-Control: no-store

Pragma: no-cache

Content-Length: xxx

{

"access_token":"Fprp6k3idtlwheeTt6d2cT3RcRIMePmfOjZbmQnRZRrh",

"token_type":"Bearer",

"expires_in":"3600",

"refresh_token":"2ES542fdWGpgVl6iAstwTGsMc8Uk39Xfi67ueREkcMV3",

"scope":"name sex tel"

}

Table Response parameter (At access token reissuance (refresh))

Page 17: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

17

No Item

name

Parameter

type Parameter

name

Ma

nd

ato

ry

Forma

t

Char

acter

lengt

h

Usable

character

type

Remarks

1 Access

token

Body

(JSON)

access_tok

en

○ String 44 %x20-7E Access token.

Used when

accessing APIs.

2 Token

type

Body

(JSON)

token_type ○ String - - Value is fixed

to ”Bearer”

3 Effecti

ve

period

Body

(JSON)

expires_in ○ String - %x30-39 Seconds

indicating the

effective period

of access

tokens.

4 Refres

h

token

Body

(JSON)

refresh_tok

en

- String 44 %x20-7E Refresh token.

Used at

reissuance

(Refresh) of

access tokens.

5 scope Body

(JSON)

scope ○ String 1~

512

Each

scope

value

is %x41-5

A/%x61-

7A

%x30-39

Authorized

scope.

The following is a sample response at access token reissuance (refresh).

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

Cache-Control: no-store

Pragma: no-cache

Content-Length: xxx

{

"access_token":"Fprp6k3idtlwheeTt6d2cT3RcRIMePmfOjZbmQnRZRrh",

Page 18: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

18

"token_type":"Bearer",

"expires_in":"3600",

"refresh_token":"2ES542fdWGpgVl6iAstwTGsMc8Uk39Xfi67ueREkcMV3",

"scope":"name sex tel"

}

4.3. Response (at the time of an error)

The following table shows the specifications of the responses returned at the time of an error

No Item Description Remarks

1 Status codes 400,401,500,503 A different status code is

used for a different error

code returned.

For details, see “Table

List of Error Codes”

2 Body’s

Content-Type

application/json;charset=UTF-8

3 Body’s

Character code

UTF-8

4 Cache-Control

header

no-store

5 Pragma header no-cache

6 Body’s

Content-Length

The size of the entity body

+

Table Response parameters

No Item

name

Paramete

r

type

Paramete

r

name

Mandator

y Type

Chara

cter

string

length

Charact

er type

accepte

d

Remarks

1 Error

code

Body

(JSON)

error Yes Strin

g

- - For details, see

“Table List of

Error Codes”

Table List of Error Codes

Page 19: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

19

No Status

code

Error code Meaning Remarks

1 400 invalid_request A missing mandatory parameter,

an invalid parameter, expiry of

any effective period set for client

secret, etc.

2 401 invalid_client A request from an unregistered

client, a failed client

authentication, etc.

Sends a response

including ”WWW-Auth

enticate:Basic” in the

HTTP header.

3 400 invalid_grant An invalid authorization code or

invalid refresh token specified.

redirect_uri does not match the

one used at the time of request to

the Authorization endpoint.

4 400 unauthorized_cli

ent

A request from a client not

allowed to use grant_type

specified.

5 400 unsupported_gra

nt_type

grant_type not supported

6 400 invalid_scope An invalid scope value as shown

below.

・The scope value is null or

empty (only one-byte space is

specified)

・The same scope is specified

more than once

・An undefined scope value is

specified

・The scope value specified is not

allowed for the client who has

sent a request.

7 500 server_error An unexpected error of the

authorization server

8 503 temporarily_unav

ailable

The authorization server is

temporarily unavailable.

Page 20: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

20

Shown below is a sample of a response.

HTTP/1.1 400 Bad Request

Content-Type: application/json;charset=UTF-8

Cache-Control: no-store

Pragma: no-cache

Content-Length: xxx

{

"error":"invalid_request"

}

5. Get User ID Interface

This chapter describes the Interface for the requests and responses associated with the endpoint,

from which the ID is obtained to uniquely identify the user based on the access token.It is possible to

use this interface to obtain the user ID only if you are a subscriber of sp-mode. Application for is a

prerequisite for using this interface. Once you have applied for the API Usage please contact us via

“Support/Contact Us” section and include the name of your App that would make use of this

interface.In addition when you call the authorization endpoint and Token endpoint please include

“userid” in the scope request parameter.

5.1. Request

URL https://api.smt.docomo.ne.jp/cgi10/userid/get

HTTP method GET

HTTP header name Authorization

Description Specifies an access token

Value Specifies an access token in the form of “Bearer + Space + <access_token>”

HTTP header name X-API-Version

Description API’s version number

The version number for the initial release shall be “1.0.”

Mandatory/Option: Mandatory

Value 1.0

Shown below is a sample of a request.

Page 21: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

21

GET /userid/get HTTP/1.1

User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko)

Chrome/33.0.1750.117 Safari/537.36

Host: api.smt.docomo.ne.jp

Content-Length: 0

Authorization: Bearer Fprp6k3idtlwheeTt6d2cT3RcRIMePmfOjZbmQnRZRrh

X-API-Version: 1.0

5.2. Response (at a normal time)

The following table shows the specifications of the responses returned at a normal time.

No Item Description Remarks

1 Status code 200

2 Body’s

Content-Type

application/json;charset=UTF-8

3 Body’s

Character code

UTF-8

4 Cache-Control

header

no-store

5 Pragma header no-cache

6 Body’s

Content-Length

The size of the entity body

7 WWW-Authentic

ate

Bearer+Space+realm=”userid”

8 X-API-Version API’s version number.

Up to 8 bytes (one-byte

numerical symbols and ”.”

decimal point)

The same version

number as the request

is given to the

response for the sake

of security.

Table Response parameters

No Item

name

Paramete

r

type

Parameter

Name

Ma

nd

ato

ry

Type

Chara

cter

string

length

Character type

accepted

Remar

ks

Page 22: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

22

No Item

name

Paramete

r

type

Parameter

Name

Ma

nd

ato

ry

Type

Chara

cter

string

length

Character type

accepted

Remar

ks

1 Proces

sing

Result

code

Body

(JSON)

result_code Ye

s

String Fixed

4

bytes

One-byte number “2000

”Fixed

2 User

ID

Body

(JSON)

user_id - String - One-byte

alphanumeric

character

0x30~0x39,0x41

~0x5A,0x61~7A,

0x2B,0x2F,0x3D

(Base64-encoded

value)

Please ignore if any items other than those specified above are returned.

Shown below is a sample of a response.

HTTP/1.1 200 OK

Date: Wed, 19 Nov 2011 09:24:37 GMT

Content-Type: application/json;charset=UTF-8

WWW-Authenticate: Bearer realm=”userid”

X-API-Version: 1.0

{

"result_code":"2000",

"user_id":"UG4UUE/lHqTC6gx0cHnhbykKzmZlstJX1wNmvFBVzwq3RLgb0nayJVxqZ2RCy009"

}

Page 23: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

23

5.3. Response (at the time of an error)

The following table shows the specifications of the responses returned at the time of an error.

No Item Description Remarks

1 Status code 400,401,403,404,405,408,500,503 A different status

code is used for a

different

processing result

code returned.

For details, see

“Table List of

Processing Result

Codes”

2 Body’s

Content-Type

application/json;charset=UTF-8

3 Body’s

Character code

UTF-8

4 Cache-Control

header

no-store

5 Pragma header no-cache

6 Body’s

Content-Length

The size of the entity body

7 WWW-Authenti

cate

Bearer+Space+realm=”userid”

In case of HTTP status errors

400,401,403,it it given based on the

processing result:

error=”【Error codes character

string】”

400:error=”invalid_request”

401:error=”invalid_token”

403:error=”insufficient_scope”

Page 24: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

24

No Item Description Remarks

8 X-API-Version API’s version number

Up to 8 bytes (one-byte numerical

symbols and ”.” decimal point)

The same version

number as the

request is given to

the response.

Table Response parameters

No Item

name

Paramete

r

type

Parameter

name

Ma

nd

ato

ry

Type

Chara

cter

string

length

Charact

er type

accepte

d

Remarks

1 Proces

sing

result

code

Body

(JSON)

result_code Ye

s

String Fixed

4

bytes

One-byt

e

number

For details, see

“Table List of

Processing

Result Codes.”

Table List of Processing Result Codes

No Categ

ory Status code

Status Processing

result code

Details

1 Norma

l

system

200 Normal end 2000 Normal

2 Abnor

mal

system

400 Invalid request 4000 Invalid

parameter

(a version

number not

allowed, etc.)

3 401 Invalid

authentication status

4100 An access

token that does

not exist or

access token

no longer valid

Page 25: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

25

No Categ

ory Status code

Status Processing

result code

Details

4101 The user does

not exist

(not subscribed

to sp mode)

4 403 No access right 4500 Mismatched

scopes

5 404 Request URL not

available

- -

5 405 Method not allowed - -

6 408 Timeout 3001 Temporary

congestion,

etc.

7 500 Internal processing

error

- -

8 503 Service not

available

3002 Overload

status, etc.

Shown below is a sample of a response.

HTTP/1.1 401 Unauthorized

Date: Wed, 19 Nov 2011 09:24:37 GMT

Content-Type: application/json;charset=UTF-8

WWW-Authenticate: Bearer realm=”userid”

error=”invalid_token”

X-API-Version: 1.0

{

"result_code":"4100"

}

Page 26: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

26

6. Common References for APIs

This chapter describes request, responses, and common error codes.

6.1. Request

The query parameter of a request must include the APIKEY parameter in order to execute an API.

Please note that the APIs for Photo Collection, Data Storage BOX, and DOCOMO Phonebook are

not supported by the APIKEY parameter. For these APIs not supported, please see the functional

references for the respective APIs.

Query parameter

name

APIKEY

Description API key. This is a key uniquely assigned to each application.

Mandatory/Optional: Mandatory

Value Alphanumeric characters

Shown below is a sample of a GET request.

GET /knowledgeQA/v1/ask?q=人類初の宇宙飛行士は&APIKEY=<API key> HTTP/1.1

User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko)

Chrome/33.0.1750.117 Safari/537.36

Host: api.apigw.smt.docomo.ne.jp

Connection: keep-alive

Accept: application/json

User-Agent: <each client>

Accept-Encoding: gzip,deflate,sdch

The authorization header of a request must include an access token in order to execute an API

requiring user authorization.

HTTP header

name

Authorization

Description OAuth authentication Authorization header

Mandatory/Optional: Mandatory if the application uses any API requiring

authorization

Value Specifies an access token in the form of “Bearer + Space + <access_token>.”

Shown below is a sample of a POST request of an API requiring user authorization.

Page 27: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

27

POST /1/contact/add?APIKEY=<APIKEY> HTTP/1.1

User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko)

Chrome/33.0.1750.117 Safari/537.36

Host: phonebook-api.smt.docomo.ne.jp

Content-Type: application/json; charset=utf-8

Content-Length: 1234

Authorization: Bearer <access_token>

{

"key" : "value"

}

6.2. Response

Shown below is a sample of a response.

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

Date: Fri, 01 Nov 2013 10:13:46 GMT

Content-Length: 286

Connection: keep-alive

{

code: “S020010”,

message:

{

textForDisplay: “インターネットで調べたところ、一位は、ガガーリンです。”,

textForSpeech: “インターネットで調べたところ、一位は、ガガーリンです。”

},

answers: [

{

rank: “1”,

answerText: “ガガーリン”,

linkText: “ページ a タイトル”,

linkUrl: “http://aaa.aaa.com”

},

{

Page 28: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

28

rank: “2”,

answerText: “ユーリイ・ガガーリン”,

linkText: “ページ b タイトル”,

linkUrl: “http://bbb.bbb.com”

}

]

}

6.3. Common Error Codes

This section describes the common error codes returned by the docomo Developer support system to

the all APIs, except those of Photo Collection, Data Storage BOX, and DOCOMO Phonebook,

which are not supported by these common codes. For those APIs not supported, please see the

functional references for the respective APIs.

・List of error messages

Error type Error details

/Description

Error codes

(messageId)

Error type Error output

details (text)

HTTP

Stats

Code

Reason

phrase

1 Authentic

ation/

authorizat

ion

1. A basic

authentication

error due to

an invalid

user name or

password

POLSLA008 policyExce

ption

-UNAUTHORI

ZED- Check

the

username/pass

word

401 Unautho

rized

2. An

authentication

error due to

an invalid

APIKEY

name or

APIKEY

value.

POLSAL009 policyExce

ption

Unable to

perform

ApiKey based

Authentication

401 Unautho

rized

3. An

authorization

error

POL0001 policyExce

ption

-ACCESS

DENIED-

Service not

403 Forbidd

en

Page 29: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

29

associated with

ServiceGroup

2 CoS 1.An access

exceeding

maximum

throughput

allowed

POLSLA001 policyExce

ption

Access denied

for crossing the

maximum TC

messages

403 Forbidd

en

2.An access

exceeding

maximum

volume

allowed

POLSLA002 policyExce

ption

Access denied

for crossing the

maximum VC

messages

403 Forbidd

en

3.An access

to an

unusable

API

POLSLA005 policyExce

ption

Access denied

for accessibility

403 Forbidd

en

3 Southbou

nd

Throttling

1. An access

exceeding the

threshold for

the number of

requests

THRL004 policyExce

ption

Request rate

reached, Please

try after

sometime

403 Forbidd

en

4 OAuth

resource

server

1. An access

without an

access token

OAUTHE001 policyExce

ption

OAuth Access

Token is null or

empty in the

request

403 Forbidd

en

2. An access

token

invalid

error

OAUTHE002 policyExce

ption

Invalid OAuth

Access Token

in the request

403 Forbidd

en

3. An OAuth

server error

OAUTHE003 policyExce

ption

Error in getting

access token

details from

OpenAM

OAuth2.0

Authorization

server

503 Service

Unavail

able

Page 30: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

30

5 Interface 1. An

endpoint

connection

error

SVCEXCP50

3

policyExce

ption

A error

message is

issued

according to

the error

pattern of an

EndPoint

connection

error.

503 Service

Unavail

able

2. An invalid

request

message

SVCEXCP40

0

policyExce

ption

String index

out of range: -1

400 Bad

Request

*1 In case of a Reset response in connecting to the endpoint (Connection Refuse): Connection

refused

In case of a failed connection to the endpoint (Connection not open): No route to host

In case of no response after connected to the endpoint (Response timeout): Read timed out

In case of a forced disconnection after connected to the endpoint (Response close):

Connection reset, etc.

・Error response message format

ResponsesContent-Type application/json; charset=ISO-8859-1

・Error response parameters

No. Parameter Description Mandatory Type

1 requestError Error response Yes Object

2 requestError/policyException Response

information

Yes Object

3 requestError/policyException@messageId Error code Yes String

4 requestError/policyException@text Error details Yes String

Page 31: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

31

・A sample of an error response

{

"requestError":{

"policyException":{

"messageId":"POLSLA008",

"text":"Unable to perform ApiKey based Authentication"

}

}

}

Page 32: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

32

(Appendix 1) List of scopes

This appendix shows the values that can be set in the scope parameter of the authorization endpoint

described in 3.1. For the scope parameter, please specify a value of “scope (English name)” in the

table below.

API name scope(Japanese name) scope(English name)

Photo

Collection

写 真 ・ 動 画 リ ス ト の 取 得

(acquisition of photo/video lists)

PhotoGetContentsList

写真・動画の取得 (acquisition of

photo/video)

PhotoGetContent

写 真 ・ 動 画 の ア ッ プ ロ ー ド

(upload of photo/video)

PhotoUploadContent

クラウド空き容量の確認 (check

the available size of the cloud)

PhotoGetVacantSize

グ ル ー プ 情 報 の 取 得

(acquisition of group information)

PhotoGetGroupInfo

グループ情報の編集 (editing of

group information)

PhotoUpdateGroupInfo

回転情報の変更 (update of

rotate information)

PhotoUpdateRotateInfo

ごみ箱情報の編集 (editing of

trash information)

PhotoUpdateTrashInfo

「 友人の写真 」情報の取得

(acquisition of “friend’s photo”

information)

PhotoGetFriendsPhotoInfo

DOCOMO

Phonebook

マイプロフィールの利用 (use of

My Profile)

PhonebookAccessProfile

連絡先の利用 (use of a contact) PhonebookAccessContact

連絡先の追加 (addition of a

contact)

PhonebookAddContact

友達のタイムラインへ情報を配

信 (post information to the

timeline of a friend)

PhonebookPostFeed

つ な が り 情 報 等 を 取 得

(acquisition of

“Tsunagari(connection)”

*To be provided in future

Page 33: Common Reference for docomo Developer support APIs Version 2.0 · 2019-06-14 · Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for details. 2

NTT DOCOMO Confidential

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

33

information, etc.

Data Storage

BOX

サービス専用フォルダへのアクセ

ス (access to a special folder of

the service)

DataboxAll