Tapkey for Vertical Solutions.

How to easily connect with Tapkey.

Authorization Options for OAuth Apps

Tapkey acts as a OAuth 2.0 compliant partner, enabling Tapkey users to
authorize clients to access selected resources. It is highly recommended to
familiarize with RFC 6749 prior to
reading this document.

Basic OAuth flow

  1. Authentication: Users are redirected to request their Tapkey identity and
    to negotiate scopes
  2. Authorization: The client exchanges an authorization code for an access
    token
  3. Accessing protected resources: The client accesses the resource server
    (Tapkey API) with the user's access token

Authentication

RFC 6749

This step corresponds with section 4.1.1 of the OAuth 2.0
Authorization Framework standard.

The client application redirects to Tapkey's authorization endpoint located at

GET https://tapkey.com/connect/authorize

with the following parameters:

Name Description
client_id Required. The client ID as issued during the Tapkey OAuth client application process.
redirect_uri Required. The URL in the client application where users will be sent after authorization.
response_mode Can be query or form_post. Defaults to query.
response_type Required. Must be set to code.
scope Required. A space delimited list of scopes. A summary of available scopes can be found in the table below.
state An unguessable random string. It is used to protect against cross-site request forgery attacks.1 Typically 32 byte length.

Authorization

RFC 6749

This step corresponds with section 4.1.3 of the OAuth 2.0
Authorization Framework standard.

If the user accepts the client's request to gain access to selected resources,
Tapkey redirects back to the client with a temporary authorization code in a
code parameter (see [response modes](#Response modes)) as well as the state
provided in the previous step in a state parameter. If the states don't match,
the process must be aborted. The redirect furthermore contains a scope
parameter, that reflects the selection of scopes the user has actually granted.
The user is free to grant any combination of scopes from the list of scopes
initially requested by the client. The client is responsible for handling cases
where the user did not grant all scopes requested.

The code can then be exchanged for an access token (for accessing the Tapkey
API2) using the token endpoint

POST https://tapkey.com/connect/token

with the following parameters:

Name Description
client_id Required. The client ID as issued during the Tapkey OAuth client application process.
client_secret Required. The client secret as issued during the Tapkey OAuth client application process.
code Required. The authorization code (as specified in the authorization_code grant type).
grant_type Required. Must be set to authorization_code.
redirect_uri The URL in the client application where users will be sent after authorization.

The user will be redirected to the URI specified in redirect_uri

RFC 6749

According to RFC 6749, the client_secret parameter is
optional. However, for reasons of security, Tapkey requires client_secret
to be present in any token request.

Refreshing an access token

RFC 6749

This step corresponds with section 6 of the OAuth 2.0
Authorization Framework standard.

Access tokens are issued by Tapkey with limited lifetime only. After an access
token has expired, it can no longer be used to authorize against the Tapkey
resource server (the Tapkey API). In this case, the client has to either run
through the entire process described above again, or, if requiring repetetive
user interaction is undesireable, a refresh token can be used to retrieve a new
access token from the Tapkey authorization server.

The refresh token be used to retrieve an access token using the token endpoint

POST https://tapkey.com/connect/token

with the following parameters:

Name Description
client_id Required. The client ID as issued during the Tapkey OAuth client application process.
client_secret Required. The client secret as issued during the Tapkey OAuth client application process.
grant_type Required. Must be set to refresh_token.
refresh_token Required. The refresh token issued to the client.
scope The scope of the access request as described by Section 3.3. The requested scope MUST NOT include any scope not originally granted by the resource owner, and if omitted is treated as equal to the scope originally granted by the resource owner.

To improve on security, refresh tokens issued by the Tapkey authorization server
are intended for one-time-usage only. Every time, a refresh token is used to
retrieve a new access token as described above, the client will recieve a new
refresh token as well. The client is in charge of managing refresh tokens
securely.

The following snippet is showing an exemplary response of a token refresh
request:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ij...j8vltwIXCCxGV2D9xm82tx-A",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "4a4a8fb5c4ef170a9e07e30a2f5...f1dc4f955d72c77e1ceb76ff2e1"
}

Accessing protected resources

After obtaining an access token, it can be used to call the Tapkey resource
server to manage grants, view logs or retrieve additional user information. Take
a look at the Tapkey API reference for more information.

The following snippet demonstrates an exemplary call to the Tapkey API,
requesting additional user information.

RFC 6750

The autorization method used in this example is specified in section
2.1 of RFC 6750.

GET https://my.tapkey.com/api/v1/auth/auth/userinfo

Authorization: Bearer eyJhbGciOiJSUz...O-YbBq8F7086rQi-kEbERp4dA3r0WonpHnmYcXEnA

will return the authenticated user's details, e.g.:

{
  "ownerAccounts": ...,
  "ownerAccountPermissions": ...,
  "id": "9da7db0a-....-....-....-1c81a6060daf",
  "ipId": "com.auth0",
  "ipUserName": "...@tapkey.com"
}

Grant types

Tapkey's OAuth implementation supports the standard authorization code grant
type
. The client has to follow
the specified flow to obtain an authorization code and then exchange it for a
token.

Scopes

Scope identifier Description
manage:contacts Allow to view, add and delete contacts.
manage:grants Allow to view, add and revoke grants.
offline_access Authorize client to use refresh tokens.3
read:grants Allow to list grants.
read:logs Allow to view logs of your locking devices.

Response modes


  1. https://tools.ietf.org/html/rfc6749#section-10.12
  2. https://tools.ietf.org/html/rfc6749#section-1.4
  3. https://tools.ietf.org/html/rfc6749#section-1.5