Developers Guide
Preparation
PotatoOAuth2.0 APIs use the OAuth2.0 protocol for authentication and authorization.
Before the authorization login of Potato OAuth2.0, developer should register a account in the Potato developer center, and have an approved web application or mobile application to obtain client_id and client_secret, after that the process can be started.
1. At present, Potato login on mobile apps only provides a native login mode, which requires users to install Potato client to work with it. 2. For Android apps, it is recommended to always display the Potato login button. When the Potato client is not installed on the user's phone, please guide the user to download and install the Potato client. 3. For iOS apps, it is recommended to always display the Potato login button. When the Potato client is not installed on the user's phone, please guide the user to download and install the Potato client.
Basic Steps
Potato OAuth2.0 APIs allows Potato user use Potato identity to secure access to third-party websites or applications, After the Potato user is authorized login to the third-party application that has access to the OAuth2.0, the third party can obtain the user's interface call credentials (access_token). The access_token can be used to make the API open platform authorization relationship interface call, which can realize the basic open information of the Potato user and help the user to implement the basic open function.
Potato OAuth2.0 APIs is currently in authorization_token mode. The overall process of this mode is as follows:
1. The third party initiates the Potato authorization login request. After Potato users authorize the third party application, Potato will pull up the application or redirect to the third party website with the authorization access_token. 2. Through access_token and client_secret to obtain basic data resources or help users to realize basic operations.
Download SDK
Web Apps
Server-site
When the third party uses the webapp, please guide users requesting the following URL:
https://oauth.pname.im/oauth2/authorize?response_type=token&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE
| Parameters | Required | Type | Description |
|---|---|---|---|
| response_type | yes | string | Here must be "token" |
| client_id | yes | string | The client ID for your application. |
| redirect_uri | yes | string | Determines where the API server redirects the user after the user completes the authorization flow. |
| state | no | string | Specifies any string value that your application uses to maintain state between your authorization request and the authorization server's response. |
Server Response
If the user approves the access request, then the response contains an access token.
redirect_uri?access_token=ACCESS_TOKEN&expired=EXPIRED&state=STATE
If the user does not approve the request, the response contains nothing.
redirect_uri?state=STATE
''
''
Mobile Apps
Android Mobile App
1 Put the downloaded jar package in the appropriate libs directory. (or add the jar package directly to the project by importing the external package)
It must manually import the jar package by copying it to the libs directory.
2.Add jar use permissions (skip this step if the application has been added), Add under the root node of the android manifest.xml file:
<uses-permission android:name="android.permission.INTERNET"/>3 Configure AndroidManifest.xml file. Add under the node of application.
<activity
android:name="im.potato.potato_sdk.LoginActivity"
android:configChanges="orientation|screenSize|keyboardHidden"/>4 Configure AndroidManifest.xml file. Add under the node of application
This step is not required. Please refer to step 5 for use
<meta-data
android:name = "PotatoClientID"
android:value = "YourClientId"/>5 Configure in Application Clients:
Once the ClientID is configured in AndroidManifest.xml, the AndroidManifest.xml configuration will be used regardless of the calling method.
1.Login.launchClientLogin(MainActivity) 2.Login.launchClientLogin(MainActivity.this,"YourClientId");
6 Rewrite onActivityResult in Activity.
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
if (requestCode == IdentifierUtils.sClientLoginRequestCode) {
if (resultCode == IdentifierUtils.sNetError) { // error network
String error = data.getStringExtra("error");
Log.d("error", error);
} else if (resultCode == RESULT_OK) { //token
if (data != null) {
Bundle bundle = data.getExtras();
AuthToken authToken = (AuthToken) bundle.getSerializable("getToken");
Log.d("TAG", "token:" + authToken.toString());
if (authToken.success) {
Log.d("TAG","success");
} else {
Log.d("TAG","error:" + authToken.message);
}
}
} else if (resultCode == IdentifierUtils.sNoPotatoClientID) { // configure client_id
Log.d("TAG", data.getStringExtra("error"));
} else if (resultCode == IdentifierUtils.sNoInstallPotato) { // install potato
Log.d("TAG", data.getStringExtra("error"));
}else if(resultCode == IdentifierUtils.sOAuthFail) {
Log.d("TAG", data.getStringExtra("error"));
}
}
}
iOS Mobile App
This document corresponds to SDK version 1.5. It only supports application authorization, but does not support web authorization for the time being.
1 Go to the official website to download the SDK, add all the files in the PotatoAuthorizationSDK folder to the project, the files in the folder need to be put together, as shown below:
2 Find the current SDK where the project corresponds to the Other linker flags option to add â-ObjCâ, as shown below:
3 Configure urlscheme in your own project, the identifier is Potato, and the scheme is Potato+ClientID as shown below:
4 Add the potato program to the whitelist as shown below:
5 Import “PotatoGuards.h” into your project as shown below:
6 Rewrite the following two methods in AppDelegate
7 Using class method direct invocation, success will get token and valid time, failure will return error code and error reason
APIs
UserInfo API
https://oauth.pname.im/oauth2/api/userinfo?access_token=ACCESS_TOKEN&client_secret=CLIENT_SECRET
POST
application/x-www-form-urlencoded
| Parameters | Required | Type | Description |
|---|---|---|---|
| access_token | yes | string | access token |
| client_secret | yes | string | client secret |
Server Response
success example：JSON
{
"open_id":"fHIE0JbejMjql1SaDOp-E-PZ-inFbC1uiAnq7YDJV0k=",//user's unique id
"union_id":"Triy0Fj1gnA480MVlqKakmtduDQdMUbdijXn0QJHNrM=",//developer unique id
"username":"jack",//user's username
"phone":"19912345678",//user's phone number
"country_code":"86",//the user country code
"photo_base64":"9j/2wCEAAgGBgcGBQgHBw.....",//user's avatars base64 encoded data
}
error example：JSON
{
"success" : false, // error
"code" : 4116, //response code
"message" : "missing access_token", //response message
}
- More errors
Refresh access_token
https://oauth.pname.im/oauth2/api/refreshToken?access_token={{access_token}}&client_secret={{client_secret}}
POST
application/x-www-form-urlencoded
| Parameters | Required | Type | Description |
|---|---|---|---|
| access_token | yes | string | access token |
| client_secret | yes | string | client secret |
success example：JSON
{
"success":true,
"code":0, //error code
"message":"ok",
"data":{ //token detailed information
"access_token":"CcdUEPpv0_t94WGeIakrm-rm_NwakynkftjuKFMkeoTS4bpsF3UKunITF9MsU6wqmGGF0ifNDSqaTIzNDv-lipJt9TQP7FDo8av_lV5ROEy9", //token
"expires_in":1592987431,// expiration time (time stamp, unit: second)
"token_type":"bearer",//token type
"scope":"userinfo",//extend of competence
"nonce":false // false means token can be used multiple times, true means token can be used only once
}
}
| Parameters | Type | Description |
|---|---|---|
| success | bool | whether the operation is successful or not |
| code | int | status code |
| message | string | prompt information |
| data | obj | token detailed information |
Errors (http response code always '200')
response json result. if not successful, code is:
| Error Codes | Message | Description |
|---|---|---|
| 4116 | missing access_token | require request parameter 'access_token' |
| 4117 | missing client_secret | require request parameter 'client_secret' |
| 4213 | invalid access_token | your access_token is wrong |
| 4214 | invalid client_secret | your client_secret is wrong |
| 5401 | the token has expired | your token has expired |
| 5900 | $e | unknown exception |
