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.

Info

Client credential clients are handled like regular user accounts. When they are created, they don't have any permissions assigned at first. They are independent of the user who created the client credential client and don't inherit this user's permissions). E.g.: In order to manage a certain owner account, the client credentials client needs to be assigned the co-admin permission. Read Management API section to get more details.

Info

Please note that there is a difference between scopes and permissions. Scopes indicate which endpoints the client is allowed to access, while permissions define which data the client is allowed to access via these endpoints.

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¶

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.

Info

Please note that clients using the Client Credentials flow neither act on behalf of the user who created the client, nor are able to access the owner account that holds the OAuth client. Instead, a service account that corresponds to the OAuth client is created. The service account is identified by an email in the form of <id>@iam.serviceaccount.tapkey.com, which is shown in the client's details.

Follow these instructions to grant a service account access to an owner account.

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 can manage (i.e. is co-administrator), e.g.:

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

Tip

If this operation returns an empty result ([]), your client is most likely lacking access to any owner accounts. Use the corresponding service account email to grant the client co-administrator privileges on those owner accounts, that should be managed by the OAuth client.