Exchange token flow

In this case, mini app is independent to host app, and is developed by a separated develop team.

General flow

Implementation steps for host app

1. Login to Teko IAM Backend

Please use TerraAuth to do this.

2. Register the MiniApp (that you want to exchangeIdToken for) with Teko IAM Backend

• Request MiniApp dev team to provide you an audience string that identify their MiniApp
• Contact Terra team with this audience, we will setup it for you

Implementation steps for mini app

1. In MiniAppClient, implement code to get the idToken from Hestia and send to MiniAppBackend

To get the IdToken from Hestia, according your MiniAppClient platform please refer NativeMiniApp, WebMiniApp, ReactNativeApp

2. In MiniAppBackend, implement code to verify the idToken

The idToken includes following information:

Property	Description	Type	Constraint
iss	The Issuer of the token (will be Teko IAM backend, depend on environment)	string	required
aud	The audience that this token is intended for	string	required
sub	The identifier for the user	string	required
iat	The time the token was issued	string	required
exp	Expiration time on or after which the token must not be accepted. Represented in Unix time (integer seconds)	string	required
name	User profile name	string	required
email	User profile email	string	optional
phone_number	User profile phone number	string	optional

For example, an idToken looks like this:

{

"iss": "https://oauth.stage.tekoapis.net",

"aud": "tripi-flight:12345-67890-98765-43210",

"iat": 1623901567,

"exp": 1623901867,

"sub": "ec957703c25344efa6f6659ea8186e9c",

"name": "Sample User Name",

"email": null,

"phone_number": null

}

Some fields that mini apps need to care for:

• iss to ensure that this idToken is issued by Teko IAM backend, not another untrusted sources
• aud to ensure that this idToken is for this MiniApp, not another mini app (you send this to HostApp dev team as audience before)
• sub is the user identifier

And lastly but the most important, mini app need to verify the idToken with public key from Teko IAM backend. Keep in mind that the keys are changed periodically so best practice is to get it through API below, and cache for performance:

Environment	Url to get public keys
dev	https://oauth.develop.tekoapis.net/.well-known/jwks.json
stage	https://oauth.stage.tekoapis.net/.well-known/jwks.json
production	https://oauth.tekoapis.com/.well-known/jwks.json

After idToken is verified, MiniAppBackend can issue a miniAppAccessToken for MiniAppClient.