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

Authorization code flow (OAuth 2.0)

The authentication code flow is used by applications that are hosted on a secure server. A critical aspect of the authorization code flow is that the server must be able to protect the issued client application's secret. The below figure illustrates the workflow of authorization code flow:

Authorization code 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. If the user accesses this request, an authorization code will be sent back to the web application.
  3. The web application exchanges the received authorization code to an access token at the authorization server.
  4. The web application accesses the resource server using this access token on behalf of the user.

To integrate your web server application with TogoID, 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

When redirecting a user to TogoID to authorize access to your application, you’ll need to construct the authorization URL with the correct parameters and scopes.
https://<togo-id-base-url>/connect/authorize?<authorize parameters>
Here’s a list of parameters you should always specify:

Parameter

Description

Required?

client_id

Identifier of client application using the 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 authorization code flow, response_type should be code.

Required

scope

For authorization_code flow, the scope should always be openid email profile cosmos offline_access (space characters separating each word). For more details on supported scopes in Togo ID, see Scopes.

Required

state

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

Optional but recommended

2. Prompt for consent

After successfully logging in, the user is prompted for consent to share their personal information with your application. Your application requests what information it needs in the scope parameter. If the user fails to consent to your application’s required information, then a token will not be issued and login cannot proceed. If they choose not to consent to optional information, they may continue with login and your system can handle optional or missing non-essential properties.

3. Togo ID redirects back to your application

If the user approves your application, TogoID will redirect them back to your redirect_uri with a temporary code parameter. If you specified a state parameter in step 1, it will be returned as well. The parameter will always match the value specified in step 1. If the values don’t match, the request should not be trusted.
Once the system visits the authorize endpoint and logs in, then they’re sent to the redirect_uri with a value for code.

Sample redirect_uri:
https://sample.togogroup.com/togo-callback#state=NzhkNzQ3MzllODVlMGM1Yjc4OWFkOWQ5&code=Y2NmMDk2NDkxM2U2NzNjNWQ3YWQwY2M0

You must parse this URL to obtain the code value. You should also verify that the state matches the state generated for the authorization request.

📘

Client side URL parse

The fragment portion of the URL is often not sent to servers for processing. So clients must perform initial URL parsing on client side JS or mobile app code.

4. Exchange code for an ID token

To obtain the id_token (required) and access_token (optional) you then send the code, obtained from Step 3, back to the token endpoint. This can be done by making a POST call:

Request:

POST /connect/token HTTP/1.1
Host: id2.runswithtogo.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=Y2NmMDk2NDkxM2U2NzNjNWQ3YWQwY2M0&client_id=ns4fQc14Zg4hKFCNaSzArVuwszX95X&client_secret=MWYzNGVjNjM3NmE5NGZiYzUwZmI3NDky&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_id

Identifier of client application using Togo ID server.

Required

client_secret

The client secret obtained from Togo Group for your application.

Required

grant_type

As defined in the OAuth 2.0 specification, 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,
}

Field

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 may be used by your application to authorize an 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. Make an API call

After your application obtains an ID token, you can make your first API call. To do this, include the ID token in the API request header parameter Authorization: Bearer <id_token>.

Updated about a year ago



Authorization code flow (OAuth 2.0)


Suggested Edits are limited on API Reference Pages

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