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

Hybrid flow

The Hybrid flow is a combination of the Authorization Code and Implicit flows. To use Togo API services on behalf of a user when the user is offline, you must use a hybrid server-side flow. It allows the backend of the client to receive a one-time authorization code, while the frontend can receive an ID token and/or an access token.

Hybrid flow

  1. A user goes on to a web application (OAuth client) in their browser and tries to access a service on the backend.
  2. The web application redirects the browser to an authorization server, which asks the user to give access permission for this web application.
  3. If the user accesses this request, an authorization code and depending on the Response Type, one or more additional parameters are sent back to the web application.
  4. The web application exchanges the received authorization code to an access token at the authorization server.
  5. The web application accesses the resource server using this access token on behalf of the user.

To integrate your application with TogoID using hybrid flow, follow the below steps:

Prerequisite

Before integrating with TogoID, you’ll need to register the new OAuth2 application with TogoID as described in Raising an integration request. The Togo ID server assigns a client_id and client secret. This client ID is unique for your application.
If you already have an OAuth 2.0 system in place, you may need to configure the following settings:

  • Authorize URL: https://<togo-id-base-url>/connect/authorize
  • Access Token URL: https://<togo-id-base-url>/connect/token

1. Create authorize URL

Hybrid flow initially visits the authorization endpoint and then the user is redirected to login.
https://<togo-id-base-url>/connect/authorize?<authorize parameters>

Request parameters are:

Parameter

Description

Required?

client_id

Identifier of client application using Togo ID server.

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 hybrid flow, response_type should be code id_token.

Required

scope

For hybrid flow, scope should always be openid email profile cosmos offline_access (space characters separating each word).

Required

state

A random string 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.

Optional

The user is redirected to the login page and the user logs in.

2. Prompt for user consent

After successfully logging in, the user is prompted to consent to share their personal information with your application. If they choose not to share the required information, then they cannot log in and they’re sent back to your application. If they choose not to consent to optional information, they’re allowed to proceed with login and it is assumed your system can handle optional or missing non-essential properties.

3. Parse the response

Once the user visits the authorize endpoint and logs in, then they’re sent to the redirect_uri. The redirect_uri contains the value for code, id_token, and/or token (access token) based on the return_type parameter specified in the authorization endpoint.
You must parse this URL to obtain the id_token value. You should also verify that the state matches the state generated for the authorization request.

Example:
https://sample.togogroup.com/togo-callback#state=NzhkNzQ3MzllODVlMGM1Yjc4OWFkOWQ5&code=Y2NmMDk2NDkxM2U2NzNjNWQ3YWQwY2M0&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

Feild

Description

code

The authorization code returned from the initial 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.

state

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

Optionally, you can parse the code and continue to obtain an access_token.

4. Exchange code for an access token

To obtain the access_token (optional) you then send the code back to the token endpoint. You also supply a header with the client secret to authorize your client. This can be done by making a POST call:
Authorization:
Basic <client_secret>
Request:

`POST /connect/token HTTP/1.1`
`Host: id2.runswithtogo.com`
`Content-Type: application/x-www-form-urlencoded`
`Authorization: Basic MWYzNGVjNjM3NmE5NGZiYzUwZmI3NDky`
`grant_type=authorization_code&code=Y2NmMDk2NDkxM2U2NzNjNWQ3YWQwY2M0&redirect_uri=https%3A%2F%2Fsample.togogroup.com%2Ftogo-callback`

Field

Description

Required?

code

The authorization code returned from the initial request.

Required

redirect _uri

One of the redirect URIs you listed in the integration request form.

Required

client_secret

The client secret obtained from Togo Group for your application.

Required

grant_type

This field must contain a value of authorization_code.

Required

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
  “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”,
  “access_token”: “ODc0OGM5OTU0YTQ4YTM5OGZmNmY2MTYw”,
  “token_type”: “Bearer”,
  “expires_in”: 50000,
}

Feild

Description

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.

access_token

This token is used by your application to authorize a Togo API request.

token_type

The type of token returned. At this time, this field's value is always set to Bearer.

expired_in

The remaining lifetime of the access token in seconds.

5. Call the API

Once the ID token has been obtained it can be used to make calls to the API by passing it as a Bearer Token in the Authorization header of the HTTP request.

Updated about a year ago



Hybrid flow


Suggested Edits are limited on API Reference Pages

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