Client Credentials¶

The Client Credentials Grant Type is typically used when the client (the application) is acting on its own behalf. This means that there is no actual end-user interaction in the process. The client is the owner of the resources and can act on them. The communication between these types of applications and the Tapkey Management API are also know as machine-to-machine communication.

Warning

The Client Credentials Grant Type MUST only be used by confidential clients, e.g. server-side applications.

Client application acting on behalf of an Owner Account¶

From the RFC 6749 Section 4.4:

[…] the client is requesting access to the protected resources under its control, or those of another resource owner that have been previously arranged with the Authorization Server […]

Within the Tapkey's eco-system, this translates to: A client application using the Client Credentials Grant Type is able to act on behalf of one or more Owner Accounts. Which can be done by adding this client as a co-administrator on each individual Owner Account you wish the client to control.

The Client Credentials flow¶

Authentication: The client authenticates against the Tapkey Authorization Server using its credentials and requests an access token
Authorization: The Authorization Server validates the client's authentication request and, if valid, returns an access token
Accessing protected resources: The client uses the access token to access the Tapkey Management API

Authentication and authorization¶

The client sends a request to the token endpoint

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

with the following parameters using the application/x-www-form-urlencoded format with a character encoding of UTF-8 in the request body

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.
`scope`	Required. A space delimited list of scopes. The available scopes can be found here.
`grant_type`	Required. Must be set to `client_credentials`.

The client is returned an access token in exchange.

Information

Refresh tokens are not supported for the Client Credentials Grant Type.

The following snippet shows an exemplary response of a token request:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ij...j8vltwIXCCxGV2D9xm82tx-A",
  "expires_in": 3600,
  "token_type": "Bearer",
}

Accessing protected resources¶

After obtaining an access token, it can be used to call the Tapkey Management API to manage grants, view logs or query the users locking devices. Take a look at the available operations to learn about the endpoints Tapkey provides.

The following snippet demonstrates an exemplary call to the Tapkey Management API, requesting the owner accounts which this OAuth client can manage.

RFC 6750

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

GET https://my.tapkey.com/api/v1/owners

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

will return the owner accounts which this OAuth client is an admin, e.g.:

[
  {
    "id": "1",
    "name": "Home",
    "active": true
  },
  {
    "id": "2",
    "name": "Office",
    "active": true
  }
]

Info

Remember that the client only has access to owner accounts which it was given permission as admin.