Embedding Apps

This page describes how to integrate JINS MEME API into your web app or iOS/Android app.

Integrating JINS MEME API into a Web app

Authorization code flow

An access token is required to access the JINS MEME API. The access token is obtained based on the OAuth 2.0 authorization code flow. To use the authorization code flow in an app, the app must be able to send requests to the server and receive data from the JINS platform to the app. The authorization code flow is outlined below.

JINS Login Flow

The steps involved in the authorization code flow are as follows

  1. the user performs the app login operation
  2. the app sends the JINS login authorization URL to the browser, and the browser opens the login screen
  3. The user authenticates the login. After the user’s credentials are verified by the JINS platform, the user agrees to grant the authorization requested by the app.
  4. Redirect the user from the JINS platform to the app via redirect_uri. At this time, a query string containing the grant code and state is also sent to the app.
  5. The app requests an access token using the gramt code. The JINS platform verifies the request from the app and returns the access token to the app.
  6. The app can call the API with the obtained access token.

Request authorization

To request that a user authenticate and authorize your app, redirect the user to the authorization URL below with the required query parameters. To redirect the user, use a direct link.

https://accounts.jins.com/jp/ja/oauth/authorize

The required query parameter must be included in the URL.

parametertypeRequireddescription
response_typeStringRequired“code” fixed. By specifying this value, an authorization code is returned from the JINS platform.
client_idStringRequiredapp_id, which is the app ID dispensed when an app with the platform “Web” is registered with JINS MEME DEVELOPERS.
redirect_uriStringRequiredCallback URL (URL encoding required). The URL to which the user is redirected after authentication and authorization. It must exactly match the callback URL registered with the application in JINS MEME DEVELOPERS.
stateStringRequiredA unique alphanumeric string to prevent cross-site request forgery. Must be randomly generated by the application.
scopeStringRequiredUser-granted permissions; multiple scopes can be specified, separated by URL-encoded whitespace (%20). For more information, see Scope.
service_idStringRequiredfixed to “meme”.
login_hintStringOptionallogin email address. The specified e-mail address is set to the e-mail address on the login.

The scopes that can be specified for the scope parameter are as follows. Multiple scopes can be specified, separated by URL-encoded whitespace (%20). At least one scope must be specified.

ScopeDescription
officialJINS MEME OFFICIAL application data (15 and 60 second interval).

Authorization Request Example

The following is an example of an authorization URL with query parameters.

 https://accounts.jins.com/jp/ja/oauth/authorize?response_type=code&client_id=123456789012345&redirect_uri=https%3A%2F%2Fexample.com%2Fcb&state=12345abcde&scope=official&service_id=meme&login_hint=test@example.com

Authentication and Grant Process

If the user is not logged in to JINS

The user is redirected to the JINS login screen for authentication. The user must log in to JINS using his/her email address and password. After logging in, the authorization screen will be displayed.

login screen

If a user session exists and the user is already logged in to JINS

The authorization screen will be displayed instead of the JINS login screen.

Authorization screen

Obtain grant code

Once the user has been authenticated and granted, a callback URL containing HTTP status code 302 and the following query parameters will be returned.

ParametersTypeDescription
codeStringGrant code used to obtain the access token. The validity period is 10 minutes. Also, the grant code can be used only once.
stateStringThe state parameter contained in the authorization URL of the original request. The app must verify that this value matches the value contained in the original request.

The following is an example response.

HTTP/1.1 302 Found
Location : https://example.com/callback?code=67890fgehi&state=12345abcde

Error Response

If the user refuses to grant the authorization requested by the app, a callback URL with the following query parameters will be returned.

ParametersTypeRequiredDescription
errorStringRequired“access_denied” fixed. This is set when canceled on the authorization screen.
error_descriptionStringRequiredError description. Human-readable ASCII-encoded text.
stateStringRequiredOAuth 2.0 state value. Returned whenever the state parameter is included in an authorization request.

The following is an example of an error response.

 https://example.com/callback?error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.&state=12345abcde

If the user refuses to grant the authorization requested by the app, the app must handle the error appropriately.

Obtaining an access token

To obtain an access token, execute an HTTP POST request with the grant code. With the obtained access token, you can call the API. Access tokens are issued at the following endpoints.

Request

POST https://apis.jins.com/meme/v1/oauth/token

Request HeaderDescription
Content-Typeapplication/x-www-form-urlencoded

Request Body

The request body information is described in form-urlencoded format.

ParametersTypeRequiredDescription
grant_typeStringrequired“authorization_code” fixed.
codeStringrequiredauthorization_code, set in the callback URL after JINS login.
redirect_uriStringrequiredcallback_url. Specify the callback URL specified in the authorization request.
client_idStringrequiredapp_id, the app ID dispensed when an app with the platform “Web” set in JINS MEME DEVELOPERS is registered.
client_secretStringrequiredApp Secret, which is the app secret issued when you register an app with the platform “Web” set up in JINS MEME DEVELOPERS.

The following is an example of an HTTP POST request to obtain an access token.

curl -X POST https://apis.jins.com/meme/v1/oauth/token \}
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code' \
-d 'code=67890fgehi' \ -d 'code=67890fgehi'
-d 'redirect_uri=https://example.com/cb' \
-d 'client_id=123456789012345' \ -d 'client_secret=123456789012345'
-d 'client_secret=67890123456789'

Response

The JINS platform validates the request from the app and returns the access token and other data to the app as shown in the table below.

PropertyTypeDescription
access_tokenStringAccess token. Validity period is 30 days.
refresh_tokenStringA token to obtain a new access token. It does not expire.
token_typeStringBearer
expires_inNumberNumber of seconds before the access token expires.
scopeStringPermissions granted by the user.

The following is an example of a JSON response.

{
  "access_token": "47912eb18a59c28550008c725ccba1074934e00c45645a882cfe47611669c298",
  "refresh_token": "47912eb18a59c28550008c725ccba1074934e00c45645a882cfe47611669c298",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "official"
}

Incorporating JINS MEME API into iOS/Android apps

Use JINS MEME API via the web app created in the previous section.

Flow from iOS/Android app

The access flow of JINS MEME API from iOS/Android app is as follows

  1. the user performs operations connected to the JINS MEME API on the iOS/Android app
  2. The iOS/Android app asks the web app for user information.
  3. The web app queries the JINS MEME API for user information.
  4. The iOS/Android application displays the results of the JINS MEME API inquiry. If the user’s authorization has been revoked, it is necessary to incorporate a process to obtain the access token again by executing the authorization code flow via the web app.