# Client Credentials Flow

As a trusted client, you can also use the Client Credentials Flow. It enables you to establish machine to machine communication. Especially in the IoT this can make sense. It is important to be aware that this only works for OAuth confidential apps.

After the token generation you will need to use the regular Access Token Refresh.

# Becoming a trusted client

Requested scopes by the Client Credentials Flow must be granted beforehand, otherwise the scope error ungranted_scope (see scope errors) will be returned.

This means that the person or organization must have successfully accepted the scopes in advance through a Redirect Flow (or through the Device Flow) for this app.

TIP

This authorization can also be done later directly through the Zaikio Hub App (via Connections), if the App has been approved by the Zaikio Team. If you want to participate, please contact us directly.

# Creating an access token

In order to create a valid access token you need send a POST request to https://hub.zaikio.com/oauth/access_token. The following parameters must accompany the request:

Name Required Description
grant_type Required The requested OAuth grant type, in this case client_credentials.
scope Required The comma-separated list of scopes containing the id of the bearer e.g. Org/b1475f65-236c-58b8-96e1-e1778b43beb7.warehouse.items.r Please read the scope guides.

After receiving the access_token (as described in the other flows). The Authorization header can be used to perform authorized requests. More details can be found in the Redirect Flow Guide.

# Authentication

When using the client credentials flow authentication needs to happen by using the HTTP BASIC authentication method, where the username is the app's OAuth client ID and the password is the app's OAuth client secret.

# On behalf of Person

In addition, the Client Credentials Flow provides the option of issuing a token for an organization, which also references a person and specifies their roles in the context of this organization in the JWT (JSON Web Token).

It is important that both the person and the organization have already been connected to the app and that the organization has already requested the required permissions in the form of scopes. Requested scopes must then receive the person and the organization in this format:

scope: Per/29b276b7-c0fa-4514-a5b1-c0fb4ee40fa7>Org/b1475f65-236c-58b8-96e1-e1778b43beb7.directory.machines.rw

If such a token was successfully requested, the following JWT payload and response is returned:

    The role attribute is represented as integer to save space, as many servers limit the header size. Since we offer a very granular role model, this is very helpful.

    This is a so-called bitfield (Wikipedia: Bitfield (opens new window)).

    For this you need the list of all existing roles with the same sorting (this is provided by us via the endpoint GET /api/v1/roles), e.g.:

    [
      "owner",
      "admin",
      "member",
      "print_admin"
    ]
    

    The bitfield can be read with following implementation: