U.ID API 1.0 Documentation API 1.0 Documentation.pdf · 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

U.ID API 1.0 DOCUMENTATION

v1.0 For Developers - English

GUNTUR AKHMAD FAUZI [email protected]

API Version: 1.0 Last update: 4/3/18 10:43:00 PM

U.ID API v1.0 Documentation – English 2

Table of Contents

API 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 8 Step 4: Refresh the Access Token 9

API Endpoints 10 GET /oauth/authorize 10 POST /oauth/token 11 GET /api/v1.0/user/info/self 12 POST /api/v1.0/user/new 16

Appendix A: API Usage Swimlane 20

Appendix B: Authorization & Access Token Flow 21

Appendix C: Consuming the API Flow 22

Appendix D: Scopes and Privileges 23

Appendix E: U.ID Standard Buttons 25


API Specifications API Version 1.0

Technology OAuth 2.0

Request types Plain, URL-encoded, Form data

Response types HTTP 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 Developer Page by clicking “Pengembang” menu on the top menu bar

3. Fill the Developer Registration form

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

b. Upload a PDF of SURAT PERMOHONAN (Application Letter)

c. Upload a PDF of DESKRIPSI APLIKASI (OAuth Application

Description)


4. Press “Mendaftar” button to send your registration.

5. Success message will be displayed, please wait for the approval or rejection

email. Your registration will be reviewed in office working hours (Monday to

Friday, 09.00-16.00), but take note that this would take hours or day.

6. Watch your email inbox for approval or rejection notification.

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

Step 1B: Create new U.ID OAuth Client 1. Login to U.ID

2. Go to Developer Page by clicking “Pengembang” menu on the top menu bar

3. You will see this page:

4. The table below will list all of your OAuth Client that has been previously

created.


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

6. Fill the form

a. Name: To identify your oAuth client (oAuth Application) for the user

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

Code sent by U.ID in the Step 2

7. Click “Buat” to create the OAuth Client

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

a. Client ID

b. Secret

9. To modify your oAuth Client settings, click on “Ubah”

10. To remove your oAuth Client, click on “Hapus”. Be aware that this action is

undoable!

Step 2: Request Code 1. To begin consuming the U.ID API, redirect your 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.

Example:

https://u.id/oauth/authorize?client_id=666&redirect_uri=https://nadia.id/callback&response_type=code&scope=basic%20email%20phone%20address_ktp%20legitimacy

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.


Step 3: Convert Code to Access Token 1. With the Authorization Code from the previous step, proceed:

2. 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.

3. 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. Use https://api.u.id as the base domain.

2. access_token valid for 60 days.

3. refresh_token valid for 90 days.


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.


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 state

2. Rejected by User

HTTP Redirect

Key Possible values

error String “access_denied”

state NULL or String your custom state


POST /oauth/token Body:

1. Converting Authorization Codes to Access Tokens

Form data Key Mandatory? Possible valid values

grant_type YES String “authorization_code”


client_secret YES String

redirect_uri YES String HTTPS URI

code YES String

2. Refreshing Access Token


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)

Privilege(s) needed:

• GET_USER_NIK

• GET_USER_NAME_FULL

• Others: optional based on your requirements

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 Name Scopes Needed

Privileges Needed

email email GET_USER_EMAIL_PRIMAR

Y

phone phone GET_USER_PHONE_PRIMAR

Y

address_ktp address_ktp GET_USER_ADDR_KTP

address_domi

cile

address_do

micile

GET_USER_ADDR_CUSTOM_

PRIMARY

legitimacy legitimacy GET_USER_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 <scope: email>

String phone <scope: phone>

E.164 international telephone numbers

phone_alternative <scope: phone>

E.164 international telephone numbers,

NULL address_ktp <scope: 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 <scope: address_domicile>

String, NULL legitimacy_level <scope: legitimacy>

Object

NIK Boolean

EMAIL Boolean

PHONE Boolean

ADDR Boolean

PRESENCE Boolean

percent Integer

2. Error

JSON Object

Key Possible values

errors String or Array of Object(s)

Example response:

1. OK

{ "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 } }


2. Error

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


POST /api/v1.0/user/new Scope(s) needed:

• basic

• email

• phone

• address_ktp

• address_domicile

• legitimacy

• registers_user

Privilege(s) needed:

• REGISTERS_USER

Header:


Authorization YES String “Bearer access_token”

X-Requested-With YES String “XMLHttpRequest”

Accept YES String “application/json”

Body:


nik YES Integer

16 digits

confirmation_string NO 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

You should not encrypt this, we

will encrypt this using our own

method.

password_confirmation YES < same as password >

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 <scope: email>

String phone <scope: phone>

E.164 international telephone numbers


phone_alternative <scope: phone>

E.164 international telephone numbers,

NULL address_ktp <scope: 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 <scope: address_domicile>

String, NULL legitimacy_level <scope: legitimacy>

Object

NIK Boolean

EMAIL Boolean

PHONE Boolean

ADDR Boolean

PRESENCE Boolean

percent Integer

4. Error

JSON Object

Key Possible values

errors String or 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" }


Appendix A: API Usage Swimlane


Appendix B: Authorization & Access Token Flow


Appendix C: Consuming the API Flow


Appendix D: Scopes and Privileges

Every data that you could get from U.ID API is governed by scope; each scope is

governed at the minuscule level by privilege. The default privileges given to

new oAuth Client are GET_USER_NIK and GET_USER_NAME_FULL. You may

request any privilege you need by utilizing our ticket feature that you could

access via your U.ID profile page.

Name Description basic Access NIK, full name, sex, birth date, birth place,

profile picture

Privileges: GET_USER_NIK

GET_USER_NAME_FULL

GET_USER_BIRTH_DATE

GET_USER_BIRTH_PLACE

email Access Email address (primary)

Privileges: GET_USER_EMAIL_PRIMARY

phone Access Phone numbers (primary & alternative)

Privileges: GET_USER_PHONE_PRIMARY

GET_USER_PHONE_ALT

address_ktp Access KTP address

Privileges: GET_USER_ADDR_KTP

address_domicile Access Domicile address


Privileges: GET_USER_ADDR_CUSTOM_PRIMARY

legitimacy Access Account verification statuses

Privileges: GET_USER_LEGITIMACY

registers_user Able to create new U.ID account

Privileges: REGISTERS_USER


Appendix E: U.ID Standard Buttons

Please use these buttons on your application when asking your user to authorize

using U.ID Account. You may hotlink the image using the provided Hotlink URL.

Image Hotlink URL

https://u.id/resources/images/button-

[email protected]


[email protected]


[email protected]


[email protected]

Documents

U.ID API 1.0 Documentation API 1.0 Documentation.pdf · 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