Server-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.

In addition, you must provide the parameter response_type with value code, indicating that we are using the server-side flow.

You can request also special permissions to the user, indicating in this URL. These permissions are called Scopes in OAuth 2.0 protocol, and are listed in a section below. The scope parameter values should be more than one, separated by commas.

All parameters provided in the API must be encoded in x-www-form-urlencoded.

Redirection example:

https://login.topoos.com/oauth/authtoken?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI
&response_type=code&scope=email

The user will be identified by their credentials in topoos login service endpoint.

topoos login endpoint

login endpoint

Once the user has successfully authenticated, he can read about what app requests access his resources, for take the decision to authorize it.

topoos app accreditation page

app accreditation

If the client authentication fails, or if the user not authorized your app, the browser will be redirected (HTTP Redirect) to the REDIRECT_URI that your specified as parameter, including the error description:

http://YOUR_REDIRECT_URI?error=access_denied

If the user authorized your application, the browser will be redirected (HTTP Redirect) to the Redirect URI that you specified, including an authorization_code.

http://YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE

With this Authorization Code your app can proceed to the next step (application authentication) to get a valid Access Token for this user that you’ll need to perform topoos API calls.

To authenticate the application, you must sign a request to the topoos API Access Token Endpoint with the obtained Authorization Code, and your CLIENT_SECRET.

This is the API Access Token Endpoint, you must use POST METHOD:

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

The CLIENT_SECRET was obtained when you registered your app, and it should not be shared with anyone or embedded in any code that is distributed (in this scenario you must use client-side flow).

POST oauth/accesstoken HTTP/1.1
Host:login.topoos.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code=AUTHORIZATION_CODE
&redirect_uri=YOUR_REDIRECT_URI

If the application is successfully authenticated in this step and the authorization code is valid, the server will responses with Access_Token object in JSON format. In addition the server provides other atributes:

  • expires_in: the time in seconds it will take to expire this Access_token
  • refresh_token: the code for get a new Access_token once this has expired.
{
    "Access_token": "72AB1F0F-128B-4701-9902-86A8D8727C48",
    "expires_in": 600,
    "refresh_token": "A2D5985D-5A05-4283-9DF4-ACAE17978603"
}

If there was a problem authenticating the application, the server returns an error in the same way:

{
    "error": "example - error - message",
    "Description": "example - error-message-description"
}

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