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 Management API is also known 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 ecosystem 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 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 resource server (i.e. 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¶

Management API¶

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

The following snippet demonstrates an exemplary call to the 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

Please note that the client only has access to the owner accounts for which it has been granted admin permissions.