Machine identity for services

A machine identity is an OAuth2 client that authenticates as a specific Dawiso account using the client-credentials grant. Unattended services, such as scheduled jobs, integrations, or scanners, use it to call the Dawiso API without a person signing in.

This client authenticates with a client secret. For a key-pair-based alternative that exchanges no secret, see OAuth2 machine identities and application scopes.

A machine identity reads exactly what its bound account can read, so the account’s space permissions decide what the service sees.

Prerequisites

Ensure you have the admin role to bind a client to an account and grant that client the account’s access.

The three binding calls below are ordinary authenticated Dawiso API requests, so send your own administrator access token with each one. Only registration and the token request are unauthenticated: registration is open, and the token request authenticates with the client’s own credentials rather than yours.

Register the client

Register the OAuth2 client and ask for the client-credentials grant:

curl -X POST https://{yourdomain}/api/oauth2/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "External link checker",
    "grant_types": ["client_credentials"],
    "redirect_uris": ["https://example.com/callback"]
  }'

The response carries client_id and client_secret. Store the secret when you receive it. It isn’t retrievable afterwards.

Bind the client to an account

Decide which account the service should act as, then bind the client to it:

curl -X PUT https://{yourdomain}/api/oauth2/clients/{clientId}/user \
  -H "Authorization: Bearer {adminAccessToken}" \
  -H "Content-Type: application/json" \
  -d '{ "userId": 42 }'

The response returns the bound account. Binding again with a different userId replaces the account rather than adding a second one: a client acts as exactly one account.

The account you choose determines what the service can access:

• An account with the admin role gives the service read access to every space.
• An account with an ordinary role gives it only the spaces that account can read. Content outside those spaces doesn’t reach the service, and the output gives no indication that anything was skipped.

Request a token

Exchange the client’s credentials for an access token:

curl -X POST https://{yourdomain}/api/oauth2/token \
  -d "grant_type=client_credentials" \
  -d "client_id={clientId}" \
  -d "client_secret={clientSecret}"

The access token identifies the bound account, so every request made with it is filtered by that account’s permissions.

Review and remove a binding

Read the account a client is currently bound to:

curl https://{yourdomain}/api/oauth2/clients/{clientId}/user \
  -H "Authorization: Bearer {adminAccessToken}"

Remove the binding when the service is decommissioned:

curl -X DELETE https://{yourdomain}/api/oauth2/clients/{clientId}/user \
  -H "Authorization: Bearer {adminAccessToken}"

Removing the binding revokes the client’s ability to obtain a token, while leaving the client registration itself in place. A client that has no binding returns 404, which distinguishes a removal from a no-op.