GET access

GET Requests an access token for a user who is member of one of the groups of the calling user's organization.

Delegated user logins provide a way for a third party to integrate Drillster into another product by way of automatically establishing a logged in user session on Drillster. That way users authenticated on the host system do not have to log in into Drillster. In fact, these users do not even have to know their Drillster credentials.

From a high level, the mechanism works as follows:

  1. The host system sends an authentication request to the Drillster API using a valid OAuth token representing the main Drillster user.
  2. Drillster checks that the user making the API call has the permission to let the requested user in into Drillster. In practice this means that the proxied user must be member of a group for which the calling user has administrative rights.
  3. If permissions are OK, Drillster will respond with a message containing a URL that includes a unique token. The token acts as a one-time login for that user.
  4. The host system then forwards the user to the given URL, or can construct its own URL on the Drillster platform using the token provided. This allows immediate access to the Drillster website. Note that strictly speaking this is not a “single sign-on” solution, but rather a delegated (or proxied) login. Once an authenticated session has been established for the user, further tokens are ignored. However, a token can only be used once to start a new session.

Resource URL

https://www.drillster.com/api/2/access/{user_id}

Parameters

Field Description
security
optional

If specified with the value ssl, the session for the logged in user on the Drillster website will only use secure pages (starting with https://). This setting is typically used to avoid browser security warnings when redirecting the user from a secure page to an insecure page. Obviously, it only makes sense to use it if the page on your website that redirects the user to Drillster is also secure.

Possible values:

  • ssl
  • plain

Response

An 2.0 Access object containing a token:

{
  "token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJXSHJrck9DMFNEcWY2VjNXYVRrblpRIiwiZXhwIjoxNDYzMDY1MDkyLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwianRpIjoiZDMyNDQ1YzEtMDAxYi00ZTkyLTgxOWMtOGUxZDcyMGQ1N2RmIiwiY2xpZW50X2lkIjoiZGNlOWM0ZDFiMTZkNGRjOGIzNDI4NjlhM2ZlNTliYjkiLCJzY29wZSI6WyJST0xFX1VTRVIiXX0.QknsrlC7BFYukHCsFhL-XGT10j8dpOcjX1yB4_bOz9k"
}

Error responses

The following error situations are possible:

ID Description
missing_field No user ID was specified
incorrect_field Illegal value for security was specified
unknown_user The specified user is unknown
not_authorized The requested user is not a member of one of your organization's groups, or you are not authorized to obtain access tokens