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

Discovering ID server's endpoints and capabilities

The Togo ID server publishes a JSON document listing its standard endpoints, supported OAuth 2.0 grants, response types, and authentication methods. These details are needed by dynamic clients and application developers to construct requests to the server.
The JSON document complies with the format specified in the OpenID Connect Discovery 1.0 specifications.

You can view the Togo ID metadata at a well-known URL which looks like this:
https://<togo-id-base-url>/.well-known/openid-configuration

Example request to get the server's metadata:
Authorization:
Basic <client_secret>
Request:
GET /.well-known/openid-configuration HTTP/1.1
Host: Host: id2.runswithtogo.com
Response:

{
  "issuer": "https://id2.runswithtogo.com/identity",
  "jwks_uri": "https://id2.runswithtogo.com/identity/.well-known/openid-configuration/jwks",
  "authorization_endpoint": "https://id2.runswithtogo.com/identity/connect/authorize",
  "token_endpoint": "https://id2.runswithtogo.com/identity/connect/token",
  "userinfo_endpoint": "https://id2.runswithtogo.com/identity/connect/userinfo",   "end_session_endpoint": "https://id2.runswithtogo.com/identity/connect/endsession"
  "frontchannel_logout_supported": true,
  "frontchannel_logout_session_supported": true,
  "backchannel_logout_supported": true,
  "backchannel_logout_session_supported": true,
  "scopes_supported": [
    "openid",
    "email",
    "profile",
    "cosmos",
    "offline_access"
  ],
  "claims_supported": [
    "sub",
    "email",
    "email_verified",
    "family_name",
    "given_name",
    "user",
    "name"
  ],
  "grant_types_supported": [
    "authorization_code",
    "client_credentials",
    "refresh_token",
    "implicit",
    "password"
  ],
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "id_token token",
    "code id_token",
    "code token",
    "code id_token token"
  ],
  "response_modes_supported": [
    "form_post",
    "query",
    "fragment"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "private_key_jwt"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

The parameters in the above JSON are described in the OpenID Provider Metadata. Some of the key parameters are explained in the below sections:

Standard endpoints

  • authorization_endpoint: The OAuth 2.0 authorisation endpoint URL. The client sends the end-user's browser to this endpoint to request their authentication and consent.
  • token_endpoint: The OAuth 2.0 token endpoint URL. This endpoint is used post an OAuth 2.0 grant to obtain an ID and / or access token.
  • userinfo_endpoint: The OpenID Connect userinfo endpoint URL.
  • end_session_endpoint: The OpenID Connect end-session (logout) URL.

Tokens

  • ID token: An ID Token, stands for the identification of the logged user which is usually in JWT format. An ID token does not contain any authorization information. The ID Token is consumed by the application and used to get user information like the user's name, email, and so forth, typically used for UI display.
  • Access token: The Access Token is a credential that can be used by an application to access an API. In Togo ID access tokens are used as bearer tokens. A bearer token means that the bearer of the access token can access authorized resources without further identification. Because of this, it’s important that bearer tokens are protected. These tokens usually have a short lifespan for improved security. That is, when the access token expires, the user must authenticate again to get a new access token.

📘

ID Token for API authorization

Though our system supports access token, at this point of time we only use ID Token to gain access to an API. This implementation is bound to change in future releases.

📘

Refresh tokens

Refresh tokens are currently not used in Togo ID.

Scopes

Used to control access to the end user’s data when requested by a client application. You can validate the OAuth scopes in the incoming message against the scopes registered in the API gateway. Scopes provide users using third-party apps the confidence that only the information they choose to share will be shared, and nothing more. The below table lists all the scopes supported in Togo ID:

Scope

Description

openid

Required; to indicate that the application intends to use OIDC to verify the user's identity

email

Used to send the welcome email for verification.

profile

Used to collect user’s personal information.

cosmos

Used to access the Togo FleetTogo Fleet - A digital platform for RV rental operations, booking, and fleet management. API.

offline_access

Used to obtain an access token that grants access to the user’s data even when the user is not logged in.

Claims

OpenID Connect specifies a set of standard claims or user attributes. They are intended to provide the client with consented user details such as email, name, and other personal details, upon request.

Claim

Type

Description

sub

String

Subject. Togo account ID of the user. This must be stored in your system to perform a match.

email

String

User’s preferred email address.

email_verified

Boolean

True if the End-User's e-mail address has been verified; otherwise false.

family_name

String

User’s last name(s).

given_name

String

First name(s) of the user.

user

String

Is a JSON serialized string assigned to the user. for more information see, Custom claim.

name

String

Full name of the user.

Custom Claim

The user claim is a Togo ID custom claim which consists of a collection of organizations and roles of the user within that organization.
An example of a Togo user claim looks like this:

"user": "{\"id\":\"de7b350e-0ef2-450e-b2ae-24aca70d8a33\",\"organizations\":[{\"isAdministrator\":true,\"organization\":{\"id\":\"09b3b974-dded-45a3-aa96-ad505c1b9cd9\",\"name\":\"Joe Marsh\"},\"roles\":[]},{\"organization\":{\"id\":\"22c981b2-3a31-4272-b7f4-f57d3c14ed88\",\"name\":\"Airstream\"},\"roles\":[{\"role\":{\"id\":\"4be4972a-99e4-4a1a-afc1-83bc83420cf2\",\"name\":\"Campervan Owner\"}}]}]}",

The ID field is the user's profile ID. It's used in the app to dynamically perform actions related to the user without having to all the provide details, and also acts as the security.
The claim also contains a list of organizations the user has a membership of and whether they are an admin or not. For each of the organizations, if the user is not an admin, the role assigned to them in that organization is displayed, which translates into what permissions they have.

Response types

The OAuth 2.0 flow you choose is represented by the response_type parameter in the authorization endpoint. The response_type value determines the authorization processing flow to be used, including what parameters are returned from the endpoints.
For example, with authorization code flow, the response_type value code indicates that the authorization flow is initiated and requests the code from the authorization endpoint and then, at the token endpoint you may request the id_token and/or token (access token).
The response types supported TogoID are:

Flow

response_type value

Authorization Code

code

Implicit

id_token
id_token token

Hybrid

code id_token
code id_token token

Updated about a year ago



Discovering ID server's endpoints and capabilities


Suggested Edits are limited on API Reference Pages

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