U.ID API 1.0 Documentation API 1.0... · 2017. 5. 14. · Step 1: Register an Account 4 Step 1A:...

U.ID API 1.0 DOCUMENTATION

v1.0 For Developers - EN

GUNTUR AKHMAD FAUZI [email protected]

API Version: 1.0 Last update: 5/14/2017 4:14:00 PM

U.ID API v1.0 Documentation – English 2

Table of Contents

Specifications 3

Getting Started 4

Step 1: Register an Account 4

Step 1A: Register as U.ID Application Developer 4

Step 1B: Create new U.ID OAuth Client 5

Step 2: Request Code 6

Step 3: Convert Code to Access Token 7

Step 4: Refresh the Access Token 8

API Endpoints 9

GET /oauth/authorize 9

POST /oauth/token 10

GET /api/v1.0/user/info/self 11

POST /api/v1.0/user/new 14

Available Scopes 18


Specifications

API Version 1.0

Technology OAuth 2.0

Requests Plain, URL-encoded, Form data

Responses Headers, HTTP Redirect, JSON


Getting Started

Step 1: Register an Account

1. Register for a U.ID account at https://u.id/register

2. If you have signed up as an Application Developer, please jump to Step 1B. If

you have never signed up as an Application Developer, please proceed to

Step 1A.

Step 1A: Register as U.ID Application Developer

1. Login to U.ID

2. Go to your profile by clicking “Profil” menu on the top menu bar

3. Scroll down until you find the “Aplikasiku” section:

4. Click on the “mendaftar sebagai Pengembang Aplikasi” link.

5. Fill the form.

a. Essay should be filled with minimum of 100 words.

6. Press “Buat” button to send your registration.

7. Success message will be displayed, please wait for the confirmation. This

would take day or hours depends on the situation.

8. If you have been confirmed as Application Developer, proceed to Step 1B

https://u.id/register


Step 1B: Create new U.ID OAuth Client

1. Login to U.ID

2. Go to your profile by clicking “Profil” menu on the top menu bar

3. Scroll down until you find the “Aplikasiku” section:

4. Click on “Halaman Pengembang Aplikasi” link.

5. You will see this page:

6. The table below will lists all of your OAuth Client that has been previously

created.

7. To create new OAuth Client, lick on the “+ Buat OAuth Client” button

8. Fill the form

a. Name: To identify your client for the user

b. Redirect URL: a valid HTTPS URL that will catch the Authorization

Code sent by U.ID in the Step 2

9. Click “Buat” to save the OAuth Client


10. You should see that your application is now available to use, take notes of:

a. Client ID

b. Secret

Step 2: Request Code

1. Redirect the user to https://u.id/oauth/authorize with the following HTTP

query:

a. client_id = your Client ID

b. redirect_uri = your Redirect URI

c. response_type = “code”

d. scope = scopes you need (see section: Available Scopes), separate

each scope with single space,

example: “basic email phone”

e. state = (optional) define this parameter if your application needs to

pass state between pages. The best practice is to encode your current

state string using base64 then pass that encoded string as this

parameter value.

NOTE: The HTTP query must be URL-Encoded

2. The user:

a. If currently logged in: the approval box will be displayed,

b. If not logged in: the login box will be displayed.

3. If the user approved, the code will be sent to the redirect_uri via HTTP

query named “code”. A state HTTP query will also be sent if you defined it

on the request.

https://u.id/oauth/authorize


Step 3: Convert Code to Access Token

1. With the Authorization Code from the previous step, proceed:

2. (Make notes on using https://api.u.id as the base domain)

3. Send a POST request to https://api.u.id/oauth/token with the following data:

a. grant_type = “authorization_code”.

b. client_id = your Client ID.

c. client_secret = your Client Secret.

d. redirect_uri = your Redirect URI.

e. code = the “Code” from previous step.

4. U.ID will return a JSON response containing:

a. access_token = use this token to access all available API endpoints.

b. expires_in = seconds until the access_token needs to be

refreshed.

c. refresh_token = use this token to refresh access_token (see:

Step 4)

NOTE:

1. access_token valid for 60 days.

2. refresh_token valid for 90 days.

https://api.u.id/https://api.u.id/oauth/token


Step 4: Refresh the Access Token

1. With the access_token, proceed:

2. Send a POST request to https://api.u.id/oauth/token with the following data:

a. grant_type = “refresh_token”

b. client_id = your Client ID

c. client_secret = your Client Secret

d. scope = scopes used in this access_token, separate each scope

with single space

3. U.ID will return a JSON response containing:

a. access_token = use this token to access the API

b. expires_in = seconds until the access_token needs to be

refreshed

c. refresh_token = use this token to refresh access_token

NOTE:

1. access_token valid for 60 days.

2. refresh_token valid for 90 days.

https://api.u.id/oauth/token


API Endpoints

All below API Endpoints using https://api.u.id as the base URL.

GET /oauth/authorize

Request Body:

NOTE: Body should be URL-encoded

URL-encoded

Key Mandatory? Possible valid values

client_id YES Integer

redirect_uri YES String HTTPS URI

response_type YES String “code”

scope YES String (space-separated)

state NO

String, a custom Base64-decoded

string of your application’s current

state.

Response:

1. Approved by User

HTTP Redirect

Key Possible values

code String

state NULL or your custom st at e

2. Rejected by User

HTTP Redirect

Key Possible values

error String “access_denied”

state NULL or String your custom st at e

https://api.u.id/


POST /oauth/token

Body:

1. Converting Authorization Codes to Access Tokens

Form data


grant_type YES String “authorization_code”


client_secret YES String

redirect_uri YES String HTTPS URI

code YES String

2. Refreshing Access Token

Form data


grant_type YES String “refresh_token”

refresh_token YES String


client_secret YES String

scope YES String (space-separated)

Response:

JSON Object

Key Possible values

access_token String

refresh_token String

expires_in Integer


GET /api/v1.0/user/info/self

Scope(s) needed:

• basic

• other scopes (optional)

Header:


Authorization YES String “Bearer access_token”

X-Requested-With YES String “XMLHttpRequest”

Accept YES String “application/json”

Body:

Request Query


fields NO

String (comma-separated)

Available fields:

Field Scopes Needed

email email

phone phone

address_ktp address_ktp

address_domicile address_domicile

legitimacy legitimacy

Response:

Any:

Header

Key Possible values

X-RateLimit-Limit

Integer

The maximum allowed request-per-minute for

this API endpoint

X-RateLimit-Remaining

Integer

The remaining allowed request on this minute

for this API endpoint


1. OK

JSON Object

Key Possible values

id Integer

nik Integer

full_name String

birth_date String “yyyy-mm-dd”

birth_place String

sex String

photo URL

email

String

phone

E.164 international telephone numbers

phone_alternative

E.164 international telephone numbers,

NULL

address_ktp

Object

province String, NULL

city String, NULL

kecamatan String, NULL

kelurahan String, NULL

rw String, NULL

rt String, NULL

zip_code String, NULL

road String, NULL

address_domicile

String, NULL

legitimacy_level

Object

NIK Boolean

EMAIL Boolean

PHONE Boolean

ADDR Boolean

PRESENCE Boolean

percent Integer

2. Error


JSON Object

Key Possible values

errors String, Array of Object(s)

Example response:

1. OK

2. Error

{ "id": 6, "nik": 3173010712790012, "full_name": "SUKAB MARSUKAB", "birth_date": "1996-06-19", "birth_place": "MANADO", "sex": "women", "photo": "https://u.id/img/pp-placeholder-men.jpg", "address_ktp": { "province": "DKI JAKARTA", "city": "KOTA ADM. JAKARTA BARAT", "kecamatan": "CENGKARENG", "kelurahan": "CENGKARENG TIMUR", "rw": "16", "rt": "7", "zip_code": null, "road": "KOMP. MUTIARA GARUDA BLOK D3 NO23" }, "address_domicile": null, "legitimacy_level": { "NIK": true, "EMAIL": false, "PHONE": false, "ADDR": false, "PRESENCE": false, "percent": 20 } }

{ "errors": “Scope needed: email" }


POST /api/v1.0/user/new

Scope(s) needed:

• basic

• email

• phone

• address_ktp

• address_domicile

• legitimacy

• registers_user

Header:


Authorization YES String “Bearer access_token”

X-Requested-With YES String “XMLHttpRequest”

Accept YES String “application/json”

Body:

Form data


nik YES Integer

16 digits

parent_mother_name YES String

between 2 and 255 characters

phone YES

String

E.164 international telephone

numbers

email YES String

email format

password YES

String

minimum 8 characters

contains one of each:

• lowercase character


• UPPERCASE

CHARACTER

• Number [0-9]

• Special character [!, $, #,

%]

password_confirmation YES

accept_tos YES Integer [1 or 0]

U.ID system needs this to be: 1

Response:

Any:

Header

Key Possible values

X-RateLimit-Limit

Integer

The maximum allowed request-per-minute

for this API endpoint

X-RateLimit-Remaining

Integer

The remaining allowed request on this

minute for this API endpoint

3. OK

JSON Object

Key Possible values

id Integer

nik Integer

full_name String

birth_date String “yyyy-mm-dd”

birth_place String

sex String

photo URL

email

String


phone

E.164 international telephone numbers

phone_alternative

E.164 international telephone numbers,

NULL

address_ktp

Object

province String, NULL

city String, NULL

kecamatan String, NULL

kelurahan String, NULL

rw String, NULL

rt String, NULL

zip_code String, NULL

road String, NULL

address_domicile

String, NULL

legitimacy_level

Object

NIK Boolean

EMAIL Boolean

PHONE Boolean

ADDR Boolean

PRESENCE Boolean

percent Integer

4. Error

JSON Object

Key Possible values

errors String, Array of Object(s)


Example response:

3. OK

4. Error

{ "id": 6, "nik": 3173010712790012, "full_name": "SUKAB MARSUKAB", "birth_date": "1996-06-19", "birth_place": "MANADO", "sex": "women", "photo": "https://u.id/img/pp-placeholder-men.jpg", "address_ktp": { "province": "DKI JAKARTA", "city": "KOTA ADM. JAKARTA BARAT", "kecamatan": "CENGKARENG", "kelurahan": "CENGKARENG TIMUR", "rw": "16", "rt": "7", "zip_code": null, "road": "KOMP. MUTIARA GARUDA BLOK D3 NO23" }, "address_domicile": null, "legitimacy_level": { "NIK": true, "EMAIL": false, "PHONE": false, "ADDR": false, "PRESENCE": false, "percent": 20 } }

{ "errors": “Scope needed: email" }


Available Scopes

Name Description

basic Access NIK, full name, sex, birth date,

birth place, profile picture

email Access Email address (primary)

phone Access Phone numbers (primary &

alternative)

address_ktp Access KTP address

address_domicile Access Domicile address

legitimacy Access Account verification statuses

registers_user Able to create new U.ID account

SpecificationsGetting StartedStep 1: Register an AccountStep 1A: Register as U.ID Application DeveloperStep 1B: Create new U.ID OAuth ClientStep 2: Request CodeStep 3: Convert Code to Access TokenStep 4: Refresh the Access Token

API EndpointsGET /oauth/authorizePOST /oauth/tokenGET /api/v1.0/user/info/selfPOST /api/v1.0/user/new

Available Scopes

U.ID API 1.0 Documentation API 1.0... · 2017. 5. 14. · Step 1: Register an Account 4 Step 1A:...

Documents

Transcript of U.ID API 1.0 Documentation API 1.0... · 2017. 5. 14. · Step 1: Register an Account 4 Step 1A:...