GET access/…

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.

⚠️ Deprecation warning

Please note that this functionality will not be carried forward beyond version 2.1.1 of the API. The service accounts functionality may be used instead to accomplish the same thing in a more standardized way.

From a high level, the mechanism works as follows:

The host system sends an authentication request to the Drillster API using a valid OAuth token representing the main Drillster user.
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.
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.
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 and plain

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` and `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