Togo ID

The Togo Group Developer Hub

Welcome to the Togo Group developer hub. You'll find comprehensive guides and documentation to help you start working with Togo Group as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Implicit flow

The implicit flow is used by client applications residing in the user's device. These client applications cannot keep the client application secret confidential.
In the implicit flow, instead of issuing the client an authorization code, issues an access token directly after the user is authorized. The grant type is implicit, as no intermediate credentials are issued. Implicit grants improve the responsiveness and efficiency of some clients since it reduces the number of round trips required to obtain an access token.
The below figure illustrates the workflow of implicit code flow:

Implicit flow

At a high-level, this flow has the following steps:

  1. Your application directs the browser to the Togo ID login page, where the user authenticates.
  2. Togo ID redirects the browser back to the specified redirect URI, along with access and ID tokens as a hash fragment in the URI.
  3. Your application extracts the tokens from the URI.
  4. Your application can now use these tokens to call the resource server (for example an API) on behalf of the user.

To integrate your client-side web application with Togo ID, follow the below steps:

1. Generate a login URL

To authenticate the user, your system must generate a URL to take the user to login. And then send the user to the redirect URL.
https://<togo-id-base-url>/login?<login parameters>

Here’s a list of parameters you should always specify:

Parameter

Description

Required?

profile

Determines the style of the web page. Use togo unless directed otherwise.

Required

behaviourProfile

Determines the behavior of accounts created. Use togo unless directed otherwise.
Note the British spelling behaviour in this parameter.

Required

client_id

Identifier of client application using Togo ID server.

Required

ReturnUrl

The URL to “return” the user to after successful login. This is usually always a token generation URL. Not to be confused with the client redirect_uri parameter.
ReturnUrl is the most difficult parameter to generate. It’s a URL within a URL and URL encoding can be tricky. Remember URL encode each parameter.

Optional

authorization_endpoint

It’s always https://<togo-id-base-url>/connect/authorize.

Required

nonce

An arbitrary alphanumeric number issued as a part of the generated JWT token so you can be sure the token was generated specifically for your request.

Required

redirect_uri

The full URL to your client’s registered redirect_uri. You are permitted to add additional query parameters, but the initial URL substring must match.

Required

response_type

For implicit flow, response_type should simply be id_token.

Required

scope

For implicit flow, scope should always be openid email profile (space characters separating each word). For more details on supported scopes, see Scopes.

Required

state

A random string value of 16 to 32 alphanumeric characters. State is returned to the redirect_uri so systems can match up requests to responses. This parameter must be different for each request.

Required

Example of a full login URL:

https://id2.runswithtogo.com/identity/login?profile=togo&behaviourProfile=togo&client_id=sample-production&ReturnUrl=https%3A%2F%2Fid2.runswithtogo.com%2Fidentity%2Fconnect%2Fauthorize%3Fclient_id%3Dsample-production%26nonce%3Dc7709929297c0f47645cd4e270049fd0%26redirect_uri%3Dhttps%253A%252F%252Fsample.togogroup.com%252Ftogo-callback%26response_type%3Did_token%26scope%3Dopenid%2520email%2520profile%26state%3Dac65007cf9729c9168b475452439e9fa

Sample code to generate the login URL:

let secureRandomHex = function (n) {
  n = n || 16
  let hexStr = ''
  while (n--) {
    hexStr += Math.floor(Math.random() * 16).toString(16).toUpperCase()
  }
  return hexStr
}

let generateTogoLoginUrl = function (state) {
  const clientId = 'sample-production'
  const returnUri = 'https://sample.togogroup.com/togo-callback'
  let loginParams = {
    client_id: clientId,
    nonce: secureRandomHex(16),
    redirect_uri: encodeURIComponent(returnUri),
    response_type: 'id_token',
    scope: encodeURIComponent('openid email profile'),
    state: state
  }
  let firstParam = true
  return Object.keys(loginParams).reduce(
    function (url, key) {
      let andChar = (firstParam ? '' : '&')
      firstParam = false
      return (url + encodeURIComponent(`${andChar}${key}=${loginParams[key]}`))
    },
    generateTogoLoginUrlPrefix()
  )
}

let generateTogoLoginUrlPrefix = function () {
  const authorizationEndpoint = 'https://id2-staging.runswithtogo.com/connect/authorize'
  const profile = 'togo'
  const behaviourProfile = 'togo'
  const issuer = 'https://id2-staging.runswithtogo.com/'
  const profileEncoded = encodeURIComponent(profile)
  const behaviourProfileEncoded = encodeURIComponent(behaviourProfile)
  const profileStr = (
    `profile=${profileEncoded}&` +
    `behaviourProfile=${behaviourProfileEncoded}&`
    `client_id=${clientId}&`
  )
  const returnUrlPrefix = encodeURIComponent(authorizationEndpoint + '?')
  return `${issuer}login?${profileStr}ReturnUrl=${returnUrlPrefix}`
}

let startTogoLogin = function (state) {
  state = state || secureRandomHex(16)
  window.location.href = generateTogoLoginUrl(state)
}
public static String ByteArrayToString(byte[] inputArray)
{
    StringBuilder output = new StringBuilder("");
    for (int i = 0; i < inputArray.Length; i++)
    {
        output.Append(inputArray[i].ToString("X2"));
    }
    return output.ToString();
}
public static String SHA1Encrypt(String phrase)
{
    UTF8Encoding encoder = new UTF8Encoding();
    SHA1CryptoServiceProvider sha1Hasher = new SHA1CryptoServiceProvider();
    byte[] hashedDataBytes = sha1Hasher.ComputeHash(encoder.GetBytes(phrase));
    return ByteArrayToString(hashedDataBytes);
}
public static string GenerateNonce()
{
    Random r = new Random();
    DateTime created = DateTime.Now;
    string nonce = Convert.ToBase64String(Encoding.ASCII.GetBytes(SHA1Encrypt(created + r.Next().ToString())));
    nonce = nonce.Replace("=", "");
    return nonce;
}
public static string GenerateState()
{
    return GenerateNonce();
}
public static string GenerateTogoLoginUrl)()
{
    string baseUrl = "https://id2.runswithtogo.com/identity";
    string state = GenerateState();
    string nonce = GenerateNonce();
    string authorizeEndpoint = "/connect/authorize";
    string clientId = "sample-mobile-app";
    string scope = "openid email profile";
    string scopeEncoded = Uri.EscapeDataString(scope);
    string redirectUri = "sample-togogroup-app://oauth_redirect";
    string redirectUriEncoded = Uri.EscapeDataString(redirectUri);
    string responseType = "id_token";
    string responseTypeEncoded = Uri.EscapeDataString(responseType);
    string returnUrl = $"{baseUrl}{authorizeEndpoint}?client_id={clientId}&nonce={nonce}&redirect_uri={redirectUriEncoded}&response_type={responseTypeEncoded}&scope={scopeEncoded}&state={state}";
string returnUrlEncoded = Uri.EscapeDataString(returnUrl);
    string loginUrl = $"{baseUrl}/login?profile=togo&behaviourProfile=togo&client_id={clientId}&ReturnUrl={returnUrlEncoded}";
    return loginUrl;
}

2. Redirect the user

When the user logs in with their Togo ID, their browser is redirected to the registered redirect_uri. The URL contains both the state (for request verification and matching) and the issued id_token. These parameters typically appear in the fragment section—not query parameters. Therefore, parsing them can be tricky and in some cases can only be done by the client’s user agent.

Example redirect URL:
https://sample.togogroup.com/togo-callback#state=YTZlYjZmOTYyMzkzN2M5Mjk5OGNmMTY1&id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjNEODk2MDFCMUQ4OEYwQzI3RjIzNTUwMERDNzlERERCNjk5RUQ0NTQiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJQWWxnR3gySThNSl9JMVVBM0huZDIybWUxRlEifQ.eyJlbWFpbCI6ImpvZUBtLnRlc3QiLCJnaXZlbl9uYW1lIjoiSm9lIiwiZmFtaWx5X25hbWUiOiJNYXJzaCIsInVzZXIiOiJ7XCJpZFwiOlwiZGU3YjM1MGUtMGVmMi00NTBlLWIyYWUtMjRhY2E3MGQ4YTMzXCIsXCJvcmdhbml6YXRpb25zXCI6W3tcImlzQWRtaW5pc3RyYXRvclwiOnRydWUsXCJvcmdhbml6YXRpb25cIjp7XCJpZFwiOlwiMDliM2I5NzQtZGRlZC00NWEzLWFhOTYtYWQ1MDVjMWI5Y2Q5XCIsXCJuYW1lXCI6XCJKb2UgTWFyc2hcIn0sXCJyb2xlc1wiOltdfSx7XCJvcmdhbml6YXRpb25cIjp7XCJpZFwiOlwiMjJjOTgxYjItM2EzMS00MjcyLWI3ZjQtZjU3ZDNjMTRlZDg4XCIsXCJuYW1lXCI6XCJBaXJzdHJlYW1cIn0sXCJyb2xlc1wiOlt7XCJyb2xlXCI6e1wiaWRcIjpcIjRiZTQ5NzJhLTk5ZTQtNGExYS1hZmMxLTgzYmM4MzQyMGNmMlwiLFwibmFtZVwiOlwiQ2FtcGVydmFuIE93bmVyXCJ9fV19XX0iLCJzdWIiOiI3MzY4ZWQ2OC1iODRjLTQyMmMtOWFhNi1lMDU3NWIxMzA4YTMiLCJqdGkiOiJhNWYzMGY3OS0wMmNhLTQyMGItOTIwNi04M2VhMTAxMzA1ZTAiLCJ1c2FnZSI6ImlkX3Rva2VuIiwiYXVkIjoicm9hZHRyaXBwZXJzLWlvcyIsIm5vbmNlIjoidHBQVmZUWnlmdmcyYTF5NGY3SEhTWERvNU84eXRpRzBwWkNoS2J3U2N5ayIsImF6cCI6InJvYWR0cmlwcGVycy1pb3MiLCJuYmYiOjE1MzU2MzUyMTcsImV4cCI6MTUzNTcyMTYxNywiaWF0IjoxNTM1NjM1MjE3LCJpc3MiOiJodHRwczovL3N0YWFjY291bnRzLnRobG9ubGluZS5jb20vIn0.N4KaorKD6SDCUot_AU9Kt0xZesI23g4FL4F2bl8-H_09OcvrEM5WnZDimr5IsGOCzf49HkBX6ViELbyLusdOa45KK3elQAY0k67mfOVUiBRR2PTl-oG2MZKryIWOBpxuj5doiaw-S71bYj3jupvNtfUhA1LUHdNfl2wf9QF8J8ipQvLRDf2nUVJgUy2R8wLDejACFdnSjwbhplYQYXPlol8iq6YnZr7TV3olyWeOGpOguXfZxW00R-aqrKX9xOPInpLc88B6AmwioCYYpiPD7U2-ugAGNEGbJZPKTfCLIvPNg6k8mt943RD_GcYixFoB3NKyLhl3v24KgKkUtAnQ97Y6vfY7Fj5DWOFT0jE2m3m6D7cwvLSjcauoGLxy6YV21BPqU7epwH9OKy-xkH_5ZSpcDVFU_dGYRTx9XwcP2jck-myxzM-SK9Aa4EuYMnIqOAMdSmitQT33GqcAqr5vbSjfztNwjPM1br2Od5cufYLw4AlyUsQz8ZsZrwTKnsHXpmoyLEG2I4QUsYeyTRYvGOfw1PE9V5hwKzdms-z0d-HGt5PIJslFEE3dE_ZnUvo0tCnwgG3jLnIfBc6iMa5U2Taw8xLsudcJs-yGSQSk1t_IJiDJ8t08LqJxdmx9-QA94nIUDUWXf-goVczviOTaT6JnpSY7nuSk-I1vP_jd_54

state

A random string value of 16 to 32 alphanumeric characters. The state value must match the state generated for the authorization request.

id_token

The value is a JSON Web Token (JWT) that contains digitally signed identity information about the user. For more information on parsing the ID token, see Parsing the ID token.

3. Parse the fragment

Use the below sample code to parse the fragment (Javascript) to extract the ID token:

function getUrlParamOrFragmentValue(url, name) {
  name = name.replace(/[\[]/, '\\[').replace(/[\]]/, '\\]');
  var regex = new RegExp('[\\#?&]' + name + '=([^&#]*)');
  var results = regex.exec(url);
  var val = '';
  if (results !== null) {
    val = decodeURIComponent(results[1].replace(/\+/g, ' '));
  }
  return val;
}

4. Use the ID token to make API calls

After you have validated the ID token, you can use the ID token to make API calls. To do this, include the ID token in an API request using the parameter Authorization: Bearer <id_token> HTTP header.

Updated about a year ago



Implicit flow


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.