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.
The steps involved in the authorization code flow are as follows
- the user performs the app login operation
- the app sends the JINS login authorization URL to the browser, and the browser opens the login screen
- 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.
- 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.
- 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.
- 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.
| parameter | type | Required | description |
|---|---|---|---|
| response_type | String | Required | “code” fixed. By specifying this value, an authorization code is returned from the JINS platform. |
| client_id | String | Required | app_id, which is the app ID dispensed when an app with the platform “Web” is registered with JINS MEME DEVELOPERS. |
| redirect_uri | String | Required | Callback 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. |
| state | String | Required | A unique alphanumeric string to prevent cross-site request forgery. Must be randomly generated by the application. |
| scope | String | Required | User-granted permissions; multiple scopes can be specified, separated by URL-encoded whitespace (%20). For more information, see Scope. |
| service_id | String | Required | fixed to “meme”. |
| login_hint | String | Optional | login 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.
| Scope | Description |
|---|---|
| official | JINS 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.
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.
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.
| Parameters | Type | Description |
|---|---|---|
| code | String | Grant code used to obtain the access token. The validity period is 10 minutes. Also, the grant code can be used only once. |
| state | String | The 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.
| Parameters | Type | Required | Description |
|---|---|---|---|
| error | String | Required | “access_denied” fixed. This is set when canceled on the authorization screen. |
| error_description | String | Required | Error description. Human-readable ASCII-encoded text. |
| state | String | Required | OAuth 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 Header | Description |
|---|---|
| Content-Type | application/x-www-form-urlencoded |
Request Body
The request body information is described in form-urlencoded format.
| Parameters | Type | Required | Description |
|---|---|---|---|
| grant_type | String | required | “authorization_code” fixed. |
| code | String | required | authorization_code, set in the callback URL after JINS login. |
| redirect_uri | String | required | callback_url. Specify the callback URL specified in the authorization request. |
| client_id | String | required | app_id, the app ID dispensed when an app with the platform “Web” set in JINS MEME DEVELOPERS is registered. |
| client_secret | String | required | App 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.
| Property | Type | Description |
|---|---|---|
| access_token | String | Access token. Validity period is 30 days. |
| refresh_token | String | A token to obtain a new access token. It does not expire. |
| token_type | String | Bearer |
| expires_in | Number | Number of seconds before the access token expires. |
| scope | String | Permissions 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.
The access flow of JINS MEME API from iOS/Android app is as follows
- the user performs operations connected to the JINS MEME API on the iOS/Android app
- The iOS/Android app asks the web app for user information.
- The web app queries the JINS MEME API for user information.
- 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.