u.id api 1.0 documentation api 1.0 documentation.pdf · with single space 3. u.id will return a...
TRANSCRIPT
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
U.ID API v1.0 Documentation – English 3
API Specifications API Version 1.0
Technology OAuth 2.0
Request types Plain, URL-encoded, Form data
Response types HTTP Headers, HTTP Redirect, JSON
U.ID API v1.0 Documentation – English 4
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)
U.ID API v1.0 Documentation – English 5
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.
U.ID API v1.0 Documentation – English 6
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”
U.ID API v1.0 Documentation – English 7
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.
U.ID API v1.0 Documentation – English 8
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.
U.ID API v1.0 Documentation – English 9
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.
U.ID API v1.0 Documentation – English 10
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
U.ID API v1.0 Documentation – English 11
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_id YES Integer
client_secret YES String
redirect_uri YES String HTTPS URI
code YES String
2. Refreshing Access Token
Form data Key Mandatory? Possible valid values
grant_type YES String “refresh_token”
refresh_token YES String
client_id YES Integer
client_secret YES String
scope YES String (space-separated)
Response:
JSON Object
Key Possible values
access_token String
refresh_token String
expires_in Integer
U.ID API v1.0 Documentation – English 12
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:
Key Mandatory? Possible valid values
Authorization YES String “Bearer access_token”
X-Requested-With YES String “XMLHttpRequest”
Accept YES String “application/json”
Body:
Request Query
Key Mandatory? Possible valid values
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
U.ID API v1.0 Documentation – English 13
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
U.ID API v1.0 Documentation – English 14
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 } }
U.ID API v1.0 Documentation – English 15
2. Error
{ "errors": “Scope needed: email" }
U.ID API v1.0 Documentation – English 16
POST /api/v1.0/user/new Scope(s) needed:
• basic
• phone
• address_ktp
• address_domicile
• legitimacy
• registers_user
Privilege(s) needed:
• REGISTERS_USER
Header:
Key Mandatory? Possible valid values
Authorization YES String “Bearer access_token”
X-Requested-With YES String “XMLHttpRequest”
Accept YES String “application/json”
Body:
Form data Key Mandatory? Possible valid values
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
U.ID API v1.0 Documentation – English 17
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
U.ID API v1.0 Documentation – English 18
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:
U.ID API v1.0 Documentation – English 19
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" }
U.ID API v1.0 Documentation – English 20
Appendix A: API Usage Swimlane
U.ID API v1.0 Documentation – English 21
Appendix B: Authorization & Access Token Flow
U.ID API v1.0 Documentation – English 22
Appendix C: Consuming the API Flow
U.ID API v1.0 Documentation – English 23
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
U.ID API v1.0 Documentation – English 24
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
U.ID API v1.0 Documentation – English 25
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-
https://u.id/resources/images/button-
https://u.id/resources/images/button-
https://u.id/resources/images/button-