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:

NameRequiredDescription
client_id Required A unique client (application) identifier obtained from GeoOp.
response_type Required Must be code as per the RFC-6749 specification.
scope Required

Space-delimited list of permissions scopes required by the client (application). If set to default the default permissions list set by the application's developer will be requested.

Currently the only supported value is default.

state Recommended An arbitrary string that will be returned by the authentication server back to the client (application). Using this string to correlate requests and responses may help prevent certain attacks, such as cross-site request forgery.
access_type Optional

Determines whether the client (application) is intended to work in offline mode. If so, the Authentication Server may issue a refresh token, which, once the current access token expires, can be exchanged by the client for a new access token without resource owner's interaction with the Server.

Allowed values are online (default) and offline.

approval_prompt Optional

Determines whether the resource owner's session may be used for automatic authentication.

Allowed values are auto (default) and force. Must be set to force if the client requires refresh token.

If set to auto, then the log in form will not be shown to the resource owner if they have already been authenticated by the Authentication Server and their current session is valid.

If set to force, then the user will be required to log in manually via the log in form, no matter whether they have already been authenticated by the Server.

redirect_uri Optional Determines where the resource owner is redirected to after successful log in. If provided, the value must exactly match one of the URIs registered by the application's developer.

/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:

NameRequiredDescription
client_id Required A unique client (application) identifier obtained from GeoOp.
response_type Required Must be implicit as per the RFC-6749 specification.
scope Required

Space-delimited list of permissions scopes required by the client (application). If set to default the default permissions list set by the application's developer will be requested.

Currently the only supported value is default.

state Recommended An arbitrary string that will be returned by the authentication server back to the client (application). Using this string to correlate requests and responses may help prevent certain attacks, such as cross-site request forgery.
approval_prompt Optional

Determines whether the resource owner's session may be used for automatic authentication.

Allowed values are auto (default) and force.

If set to auto, then the log in form will not be shown to the resource owner if they have already been authenticated by the Authentication Server and their current session is valid.

If set to force, then the user will be required to log in manually via the log in form, no matter whether they have already been authenticated by the Server.

redirect_uri Optional Determines where the resource owner is redirected to after successful log in. If provided, the value must exactly match one of the URIs registered by the application's developer.

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:

NameRequiredDescription
client_id Required† A unique client (application) identifier obtained from GeoOp.
client_secret Required† A client (application) secret obtained from GeoOp. This parameter may be omitted if the client's type is public.
grant_type Required Must be client_credentials as per the RFC-6749 specification.
scope Required

Space-delimited list of permissions scopes required by the client (application). If set to default the default permissions list set by the application's developer will be requested.

Currently the only supported value is default.

* 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:

NameRequiredDescription
client_id Required† A unique client (application) identifier obtained from GeoOp.
client_secret Required† A client (application) secret obtained from GeoOp. This parameter may be omitted if the client's type is public.
grant_type Required Must be authorization_code as per the RFC-6749 specification.
code Required A one-time authorisation code received from the Server.
redirect_uri Optional Determines where the resource owner is redirected to after successful log in. If provided, the value must exactly match one of the URIs registered by the application's developer.

* 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:

NameRequiredDescription
client_id Required† A unique client (application) identifier obtained from GeoOp.
client_secret Required† A client (application) secret obtained from GeoOp. This parameter may be omitted if the client's type is public.
grant_type Required Must be refresh_token as per the RFC-6749 specification.
refresh_token Required A refresh token received from the Server.

* 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:

NameRequiredDescription
token Required An access/refresh token that has to be revoked. If the specified token has a linked token of other kind, then both tokens will be revoked.

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."
}