GeoOP

Authentication requests are processed by the GeoOp Authentication Server located at https://login.geoop.com. The endpoints provided by the server are described below.

User-Friendly Endpoints

These endpoints provide user-friendly visual interface for logging in to the GeoOp system and granting application permissions.

/

This is the server's login page. Note that this is not an entry point and is not designed to be accessed directly.

There are two possible scenarios of how the page can behave:

1. A user manually opens the page in their browser or is redirected to it from another website.
   In this case the server silently redirects the user to the GeoOp application website.
2. A user is redirected to this page from a /oauth2/code endpoint.
   In this case the server uses the existing authentication session generated by the /oauth2/code endpoint. It may show the login form if the user has not yet been authenticated or if the client has explicitly required manual user authentication. On successful authentication it redirects the user to a third-party website or application.

/grant

This is a page where a resource owner is presented with some basic information about the application (its name and developer) and a list of permissions that they can grant to that application (the latter is not yet implemented).

If allowed by the application's developer, the resource owner may be able to choose which permissions they want to grant to the application.

OAuth 2 Endpoints

These endpoints allow third-party applications to request authorisation codes and/or access tokens utilising the OAuth 2.0 protocol.

/oauth2/code

An application that wants to get an authorisation code and later exchange it for an access token for GeoOp API has to redirect the resource owner to this endpoint.

Parameters accepted by the endpoint:

/oauth2/token

This is a multi-purpose endpoint, but the ultimate goal of using it is to receive an access token. The following sections describe various ways of how that can be achieved.

Getting an access token via the implicit grant type flow

When an application wants the access token to be included into the redirect URI, then it may use the /oauth2/token endpoint to initiate an implicit grant type flow. It has to make a GET request to the endpoint and include the following parameters:

Getting an access token via the client credentials grant type flow Not Implemented

When an application wants to receive an access token that should allow it to act on its own behalf (as a system task, for example), then it may use the /oauth2/token endpoint to initiate a client credentials grant type flow. It has to make a POST* request to the endpoint and include the following parameters:

* Please use application/x-www-form-urlencoded data encoding type when submitting POST requests.
† These parameters may be omitted if the Authorization header is used for client authentication.

On success, a JSON object of the following format will be returned:

{
    "access_token": "2YotnFZFEjr1zCsicMWpAA",
    "token_type": "Bearer",
    "expires_in": 3600
}

On error, a JSON object of the following format will be returned:

{
    "error": "invalid_grant",
    "error_code": 2007,
    "error_description": "The client is not authorised to use the specified grant type."
}

Exchanging an authorisation code for an access token

Once the application has received an authorisation code as a parameter added to the redirect URI, it needs to exchange it for an access token, which it will then use to make requests to the GeoOp API. To do that, it has to make a POST* request to the /oauth2/token endpoint and include the following parameters:

* Please use application/x-www-form-urlencoded data encoding type when submitting POST requests.
† These parameters may be omitted if the Authorization header is used for client authentication.

On success, a JSON object of the following format will be returned:

{
    "access_token": "2YotnFZFEjr1zCsicMWpAA",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
    "owner_id": 5482
}

On error, a JSON object of the following format will be returned:

{
    "error": "invalid_request",
    "error_code": 2012,
    "error_description": "No authorisation code provided."
}

Exchanging a refresh token for an access token

If the application has received a refresh token, it may use the /oauth2/token endpoint to exchange it for a new access token once the current access token has expired. To do that, it has to make a POST* request to the endpoint and include the following parameters:

* Please use application/x-www-form-urlencoded data encoding type when submitting POST requests.
† These parameters may be omitted if the Authorization header is used for client authentication.

On success, a JSON object of the following format will be returned:

{
    "access_token": "2YotnFZFEjr1zCsicMWpAA",
    "token_type": "Bearer",
    "expires_in": 3600
}

On error, a JSON object of the following format will be returned:

{
    "error": "invalid_request",
    "error_code": 2021,
    "error_description": "No refresh token provided."
}

/oauth2/revoke

This endpoint is used to revoke an existing access/refresh token. It accepts just one parameter:

The endpoint always returns a JSON response.

On success, the HTTP code will be 200 and the format of the response object will be as follows:

{
    "revoked_token": "3a8dda76d511a1cec650d4379e4afdea"
}

On error, the HTTP code will be 400 and the format of the response object will be as follows:

{
    "error": "invalid_request",
    "error_code": 2020,
    "error_description": "The token parameter is invalid or missing."
}