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.

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 a corresponding service account, which can be granted access to one or more owner accounts. This can be done by making the client's corresponding service account a co-administrator of each individual owner account you wish the client to control. This procedure is described on the registration page.

The Client Credentials Flow¶

1. Authentication: The client authenticates against the authorization server using its credentials and requests an access token
2. Authorization: The authorization server validates the client's authentication request and, if valid, returns an access token
3. 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

The client is returned an access token in exchange.

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.

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

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

will return the owner accounts which this OAuth client can manage (i.e. is co-administrator), e.g.:

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