Client-Side Flow

Users authentication and authorization are managed by redirecting the user to the topoos login service endpoint in your app.

When you request this endpoint, you must include the application ID (CLIENT_ID that was received when you registered your app) and the URL to which the user will be redirected when the authorization process is complete (this parameter is called Redirect URI). Allways Redirect_uri is requested, you must provide exactly the same. This allow topoos to perform security checks, even when this not involves the redirection after the operation.

If you have not a web server, you can use the useful fake Redirect URI Endpoint that topoos provides for this case. This Redirect URI Endpoint is called OAUTH_DUMMY_PAGE and its value is:

https://login.topoos.com/oauth/dummy

If you have a web server where you can host an endpoint, you can specify you endpoint url as Redirect URI (if you preconfigure your Redirect URI domain in your app configuration in developers panel, topoos will check that the domain in OAuth process matchs with the one that you specified for extra security).

Therefore if you use OAUTH_DUMMY_PAGE or your own domain as Redirect URI, you must include others parameters in the call:

  • response_type: the value must be token in this flow.
  • agent: its a optional parameter that specifies the client aspect that you want to use. Values can be mobile for mobile device display or default for desktop web browser display.

You should not store the client_secret on any device, as a malicious user or some kind of malware could have access to it and supplant your app.

https://login.topoos.com/oauth/authtoken?response_type=token
&client_id=CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&agent=mobile

Once the user is authenticated and he authorized the application, the browser is redirected to the redirect_uri that you specified, but instead of receiving an authorization code (using the code parameter like in the server-side flow), the redirect_uri receives directly the access_token as a fragment URI (Access Token). In addition, this redirect_uri will receive:

  • expires_in: the time in seconds it will take to expire this Access_token

http://YOUR_REDIRECT_URI#access_token=ACCESS-TOKEN
&token_type=bearer&expires_in=EXAMPLE_VALUE_600

If there was an error in the process, the browser will be redirected to redirect_uri but rather the access_token it will receive an error code.

http://YOUR_REDIRECT_URI?error=access_denied
&error_description=The+resource+owner+denied+the+request

This information can be consumed directly in your application managing the redirections, and it can get the access_token to performing API calls until it expires, or use a own server-flow as intermediate for token refreshing when the has expired.

The access_token obtained in this step is the access_token required by API operations.

If you need special scope like requesting user email, offline access or user profile data, we recommend read this guide: Requesting special scope