Sign In with Terminal 3 is a convenient way for enterprises to create accounts secured by Terminal 3 while authenticating with their own proprietary application.

It is based on the OpenID Connect protocol (Authorization Code Flow) to allow your system to verify the identity of users and to securely access publicly-available user profile data.

​
Getting started

Contact us to get started!

We will provide you with a client_id and client_secret to begin testing integration. We will also need a redirect_uri from you.

​
Authorization Flow

​
Example user scenario

Assume a user creates an account via a white-labeled onboarding process powered by Terminal 3. After successful sign up, we may redirect the user to your proprietary website, such as a User Dashboard screen.

1

We generate a “magic” link for the user to continue

https://api.terminal3.io/v1/openidc/authorize

with the following parameters:

  • response_type=code
  • scope=openid
  • client_id=<your client ID>
  • redirect_uri=https://yourSite.xyz/callback
  • state=<your state> (optional)
2

Terminal 3 authenticates the user and redirects them to your site

The user will be redirected to the provided redirect_uri with a one-time code (valid within 5 minutes) and state (if applicable)

https://yourSite.xyz/callback

with the following parameters:

  • code=<a generated one-time code>
  • state=<state from Step 1>

If a user does not have an existing session, they will be directed to the login page first.

3

Request Terminal 3 to exchange a one-time code for the access token

POST https://api.terminal3.io/v2/openidc/token
Content-Type: application/x-www-form-urlencoded
  • grant_type=authorization_code
  • code=<a generated code from Terminal 3>
  • client_id=<your client ID>
  • client_secret=<your client secret>
  • redirect_uri=https://yourSite.xyz/callback

Note, we are using our v2 API here for the token instead of v1

Token response (JSON):

{
	“scope”: “openid”,
	“token_type”: “Bearer”,
	“access_token”: “eyJ...”,
	"expires_in”: 3600,
	“id_token”: “eyJ...”
}

id_token is a JWT token that contains basic information about the user, including:

{
	“user_id”: 1,
	“<yourNamespace>_username”: "abc.xyz”
}

<yourNamespace>_username is an example application-specific data field you may choose to use

access_token is a JWT token used for accessing a particular resource via the Terminal 3 API.

GET https://api.terminal3.io/v1/openidc/user
Authorization: Bearer <access_token>

​
Validating access token

To make sure the token is provided by Terminal 3 before proceeding, you can obtain the public keys from Terminal 3 and use them to verify the token:

import * as jose from "jose";

const JWKS = jose.createRemoteJWKSet(
  new URL("https://api.terminal3.io/certs/jwks.json")
);

const { payload } = await jose.jwtVerify(access_token, JWKS, {
  issuer: "Terminal 3",
  audience: "client_id",
});

​
Requesting proprietary data fields

After having an access token, you may call the Terminal 3 API to get proprietary application-specific data fields (e.g. <yourNamespace>_username). Please discuss with us what your specific business needs are.

​
Client-side implementation

Any OpenID Connect compatible library may be used for client-side implementation. For example: https://github.com/authts/oidc-client-ts

Auth & OnboardingSegments