API docs by Redocly

Identity (v4)

Download OpenAPI specification:

Suratchanee Supphaatthasitt: suratchanee.sup@truedigital.com

Identity API Allowing any person to be uniquely and easily authorized to transparently manage his account, with all necessary credentials and devices, and consents to delegate processing of his/her information and transactions as safely as the user desires within the TrueId ecosystem. JWT is must for all APIs, as soon as account is created (exception = POST /accounts) We add SDK to enforce application level security to reach those services. The account unique identifier (/accounts.id) is typically called SSOID

Identity

API to manage accounts, credentials, devices, consents, otps

OTPs

APIs to manage OTPs

Provide an OTP answer to check if matching

< Submit OTP codes to request a match check

Authorizations:
JWT
path Parameters
id
required
string
Example: 21990712 or bT0xUV8M/hJ7ABdCk6iDhxxMhtyuuBQS8g/H6rvTmYQ=

This can be user identifier (account id) or hashing mobile number

oid
required
string
Example: b9e131f0-941c-4000-b462-493f6a95a681

The user otp unique id

Request Body schema: application/json
required
status
required
string

otp status

required
object

Responses

Request samples

Content type
application/json
{
  • "status": "verifying",
  • "inputs": {
    }
}

Response samples

Content type
application/json
{
  • "code": 10001,
  • "message": "Success",
  • "platform_module": 1109,
  • "data": {
    }
}

Resend a user OTP information

< Generate a new OTP code from existing otp (same otpid but regenerated code)

Authorizations:
JWT
path Parameters
id
required
string
Example: 21990712 or bT0xUV8M/hJ7ABdCk6iDhxxMhtyuuBQS8g/H6rvTmYQ=

This can be user identifier (account id) or hashing mobile number

oid
required
string
Example: b9e131f0-941c-4000-b462-493f6a95a681

The otp unique id

Responses

Response samples

Content type
application/json
{
  • "code": 10001,
  • "message": "Success",
  • "platform_module": 1109,
  • "data": {
    }
}

Consents

APIs to manage consent management

check if user has the given consent(s)

Confirm the user has the consent you need for your app Query "?names=personalised-marketing" to know if `Personalied Marketing' consent is given.

You can also getting all consents (no query), or multiple Query "?names=personalised-marketing,data-sharing" to get those 2

Authorizations:
JWT
path Parameters
id
required
string

the account unique id

query Parameters
names
any
Enum: "direct-marketing" "personalised-marketing" "data-sharing" "sharing-mkt" "sharing-rd" "group-consent" "group-consent-true" "group-consent-ascend" "group-consent-cpf" "group-consent-cpall" "group-consent-makro" "group-consent-lotus"

select the consent(s) names you want to check

client_id
string

client id of 3rd party to get idp consent

Responses

Response samples

Content type
application/json
Example
{
  • "code": 10001,
  • "platform_module": 1502,
  • "message": "Success",
  • "content": [
    ]
}

collect the opt-in from the user on given purpose(s)

Send the list of purposeId the user has allowed. CAREFUL - the ID to send are provided in response of GET /accounts/{ID}/consents

Authorizations:
JWT
path Parameters
id
required
integer >= 1

identifier the account

Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "purposes": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 10001,
  • "message": "Success",
  • "platform_module": 1502,
  • "report_dashboard": 0
}

Withdraw consents

Provide a list of purposes the user is opting out from

Withdraw the choice(s) of the user (optout)

Authorizations:
JWT
path Parameters
id
required
integer >= 1

data subject identifier (account id)

Request Body schema: application/json
required
PurposeId
string

Need to expose a purpose_type for frontends

withdrawnBy
string

Account identifier that request withdraw consent (sso id)

Responses

Request samples

Content type
application/json
{
  • "PurposeId": "8ffa5c2c-90dc-46af-a6fc-72f7db88b668",
  • "withdrawnBy": "88123488"
}

Response samples

Content type
application/json
{
  • "code": 10001,
  • "message": "Success",
  • "platform_module": 1502,
  • "report_dashboard": 0
}

check consent by specific collection point

Confirm the user has the consent you need for your app by specific collection point which mapping with client id Query "?names=personalised-marketing" to know if `Personalied Marketing' consent is given.

You can also getting all consents (no query), or multiple Query "?names=personalised-marketing,data-sharing" to get those 2

Authorizations:
JWT
query Parameters
names
any
Enum: "direct-marketing" "personalised-marketing" "data-sharing" "sharing-mkt" "sharing-rd" "group-consent" "group-consent-true" "group-consent-ascend" "group-consent-cpf" "group-consent-cpall" "group-consent-makro" "group-consent-lotus"

select the consent(s) names you want to check for

Responses

Response samples

Content type
application/json
{
  • "code": 10001,
  • "platform_module": 1502,
  • "message": "Success",
  • "purposes": [
    ]
}

Apps

APIs to manage application for IDP consent

list which apps the user has the given idp access too

Listing 3rd party apps the user has consented too.

Deletion requires the use of consents Step1 = GET /collectionpoints (to get purposeID for purpose=identity-provider)

Step2 = Add (allow) and Remove (withdraw)

  • Add an App = POST /accounts/{ssoid}/consents/transactions/allow
  • Remove an App = PUT /accounts/{id}/consents/transactions/withdraw
Authorizations:
JWT
path Parameters
id
required
string

the account unique id

Responses

Response samples

Content type
application/json
Example
{
  • "code": 10001,
  • "message": "Success",
  • "platform_module": 1502,
  • "report_dashboard": 0,
  • "data": [
    ]
}

2FA

APIs to perform 2-step verification

2FA verification by methods notification/email/qr

There are three methods to verify 2FA

  1. notification by user accept or decline from push message.
  2. email by user verify otp email.
  3. qr by user scan qr. If user accept and trusted_flag = 1 confirm to add trusted device, for trusted_flag = 0 don't add trusted device. If user decline don't add trusted device.
Authorizations:
JWT
path Parameters
id
required
string

The account unique id

query Parameters
client_id_requested
integer
Example: client_id_requested=213

Application client id requested 2FA

ssoid_requested
required
integer
Example: ssoid_requested=22881234

SSO id requested 2FA

device_id
required
string
Example: device_id=d97fb944ed1abeabf

Device id generated from SDK belong to device that approved

device_model
required
string
Example: device_model=iPhone7,2

Device model generated from SDK belong to device that approved

device_model_name
string
Example: device_model_name=iPhone 7

Device model name of device that approved

account_requested
required
string
Example: account_requested=0818284455'

Account requested 2FA

device_id_requested
required
string
Example: device_id_requested=LM-G710

New device id that request to trust

device_model_requested
required
string
Example: device_model_requested=3638ebe3eb4aeb5a

New device model that request to trust

google_client_id
required
string
Example: google_client_id=15994588910-ht9p8tds24s

Google client id

method
required
string
Enum: "notification" "email" "qr"
Example: method=notification

Method to verify 2FA

trusted_flag
required
string
Enum: "1" "0"
Example: trusted_flag=1

Memorize device requested from user

is_approved
string
Enum: "1" "0"
Example: is_approved=1

User approved from app which is trusted device

latlong
required
string
Example: latlong=16.56523,100.13137

Latitude and Longitude

ip_address
required
string
Example: ip_address=10.110.0.15

Client IP address

Responses

Response samples

Content type
application/json
Example
{
  • "code": 10001,
  • "message": "Success",
  • "platform_module": 1503,
  • "data": {
    }
}

Accounts

APIs to manage accounts

Display my account information (login info)

< Provides basic information to find and identify the account (e.g. to establish relationships) Coming soon = details currently transmitted by JWT, will be exposed as API

Authorizations:
JWT
path Parameters
id
required
integer
Example: 21990712

A unique identifier the account (aka. SSOID)

Responses

Response samples

Content type
application/json
Example
{
  • "code": 10001,
  • "message": "Success",
  • "platform_module": 1504,
  • "data": {
    }
}

Devices

APIs to manage devices

Display list of logged in devices information

< Provides list of devices based on user login to control concurrent login. Coming soon = first times, last times and location that user have seen those devices.

Authorizations:
JWT
path Parameters
id
required
integer
Example: 21990712

A unique identifier the account (aka. SSOID)

query Parameters
google_client_id
required
string
Example: google_client_id=1758919209.1583986247

Device id of web site which getting google client id from GA. This field is optional if client id in JWT belong to app.

Responses

Response samples

Content type
application/json
{
  • "code": 10001,
  • "message": "Success",
  • "platform_module": 1505,
  • "data": {
    }
}

Clients

APIs to manage application clients

Create new client id of partners

Provide client id of partners that need to integrate with TrueID login. Allow only partner integration team to create client id automation.

Authorizations:
JWT
Request Body schema: application/json
required
Array of objects
redirect_uri
string

Endpoint for callback URLs

scope
string

Scopes define the specific JWT node can be allowed

object
object
country
required
string

Country name

Responses

Request samples

Content type
application/json
{
  • "applications": [
    ],
  • "redirect_uri": "https://trueidcallback.artanitech.com",
  • "app_name": {
    },
  • "company_name": {
    },
  • "country": "Thailand"
}

Response samples

Content type
application/json
{
  • "code": 10001,
  • "message": "Success",
  • "platform_module": 1509,
  • "report_dashboard": 0,
  • "data": [
    ]
}

Token

APIs to manage the access token

Bridge Token

Client (TrueID App/OTT) need to exchange token of partner. API will issue new jwt of partner as client requested.

Authorizations:
JWT
header Parameters
client_id
required
integer
Example: 212

Application client id

client_secret
required
string
Example: 607ed94fb933d775beabfd9xx00

Application client secret

Request Body schema: application/json
required
grant_type
string

oauth2 token exchange grant type

requested_token_type
string

requested token type

subject_token
string

token that represents the identity of the party on behalf of whom the request is being made (jwt token)

audience
integer

third party client id

request_uri
Array of strings

Responses

Request samples

Content type
application/json
{
  • "grant_type": "token-exchange",
  • "requested_token_type": "urn:ietf:params:oauth:token-type:jwt",
  • "subject_token": "eyJzdWIiOiIyMTk5MjA0MCIsImRldmljZV9pZCI6IjEyMzQ1Njc4IiwicHJvZmlsZSI6eyJyZWZzIjpudWxsLCJhdmF0YXIiOiJodHRwczpcL1wvc3RnLWF2YXRhci5kbXBjZG4uY29tXC9wMzIweDMyMFwvNDBcLzIxOTkyMDQwLnBuZz9jaGs9MC40MzE3MTE0NTE1MzkyNjEwNSIsImRpc3BsYXlfbmFtZSI6IjA4MSoqKioqKioifSwiaXNzIjoiaHR0cHM6XC9cL3Nkay1hdXRoLnRydWVpZC1kZXYubmV0IiwiYXBpbV9hbiI6IlRJRHdiIiwidmVyc2lvbiI6IjIuMC",
  • "audience": 615,
  • "request_uri": [
    ]
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsInN1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NvcGUiOiJhcGkifQ.K4Ik-igqOKi_4CnBu4dG3-gGUObfgv-rJhgXVDNOWW_MHgVwddhgVLLQf_bm3xlpQM6wHrLbMaZC4LicsQC23g",
  • "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
  • "token_type": "Bearer",
  • "expires_in": 3600
}

Customers

APIs to get the customer data for Mobile ID project

To get customer information.

<| To get customer information only for MobileID project.

Authorizations:
JWT
path Parameters
mobile_number
required
string
Example: lOgjCfSGrFimL0eml5qV3A==

The customer mobile number with encryption and url encode.

query Parameters
channel
required
string
Enum: "MobileApp" "CRM" "Kiosk"
Example: channel=MobileApp

The channel from requestor. ( CRM = channel CRM , Kiosk = channel Kiosk , MobileApp = channel Mobile Application)

header Parameters
x-request_id
required
string
Example: BBLA927da5c1-0434-4eeb-b96e-fc3ec830e369

The reference request id from requestor.

x-client_id
required
string
Example: 3547

The unique id for each relying party.

x-request_datetime
required
string
Example: 2020-11-11T11:59:54

The request date and time.

Responses

Response samples

Content type
application/json
Example
{
  • "resultResponse": {
    }
}

Credentials

Create new customer credentials

< Adding an additional credential to an account to enforce security. This should only be done in a session with 2+ factors

Authorizations:
JWT
path Parameters
id
required
integer

A unique identifier the account

Request Body schema: application/json
required

Object containing customer credentials

value
required
string
type
required
string
Enum: "mobile" "email" "password" "facebook_id" "google_id" "device_id"
kind
required
string
Enum: "knowledge" "possession" "inherent" "location"
source
required
string
Enum: "user" "facebook" "google"
status
required
string
Enum: "new" "active" "inactive" "blocked"
last_verified
string
created_at
string
updated_ip
string
created_ip
required
string

Responses

Request samples

Content type
application/json
{
  • "value": "0818082899",
  • "type": "mobile",
  • "kind": "knowledge",
  • "source": "user",
  • "status": "active",
  • "last_verified": "29-Aug-19 08:30:22",
  • "created_at": "14-Aug-19 15:15:00",
  • "updated_ip": "110.170.171.178",
  • "created_ip": "110.170.171.178"
}

Response samples

Content type
application/json
{
  • "code": 10001,
  • "platform_module": 1501,
  • "report_dashboard": 0,
  • "message": "Success"
}

Retrieve list of credentials by sso id

< Listing credentials available to recover an account. Not including the private/encrypted information.

Authorizations:
JWT
path Parameters
id
required
integer

A unique identifier the account

Responses

Response samples

Content type
application/json
{
  • "code": 10001,
  • "platform_module": 1501,
  • "report_dashboard": 0,
  • "message": "Success",
  • "data": [
    ]
}

confirm customer credentials after verification

< Used to manage the status of credentials, especially set verified after successful OTP exchange

Authorizations:
JWT
path Parameters
id
required
integer

A unique identifier the account

cid
required
integer

Credential ID

Request Body schema: application/json
required

Update credential information

value
required
string
type
required
string
Enum: "mobile" "email" "password" "facebook_id" "google_id" "device_id"
kind
string
Enum: "knowledge" "possession" "inherent" "location"
source
string
Enum: "user" "facebook" "google"
status
string
Enum: "new" "active" "inactive" "blocked"
last_verified
required
string
updated_ip
required
string

Responses

Request samples

Content type
application/json
{
  • "value": "abc@gmail.com",
  • "type": "email",
  • "status": "active",
  • "last_verified": "29-Aug-19 15:05:30",
  • "updated_ip": "110.170.171.178"
}

Response samples

Content type
application/json
{
  • "code": 10001,
  • "platform_module": 1501,
  • "report_dashboard": 0,
  • "message": "Success"
}

Delete customer credentials

< Removing this credential from the account

Authorizations:
JWT
path Parameters
id
required
integer

A unique identifier the account

cid
required
integer

Credential ID

query Parameters
status
required
integer

Credentail status

Responses

Response samples

Content type
application/json
{
  • "code": 10001,
  • "platform_module": 1501,
  • "report_dashboard": 0,
  • "message": "Success"
}