Client Credentials

Use Client Credentials for supported integrations that need to obtain a token without an interactive user sign-in. This guide uses Custom Device HTTP ingestion to walk through credential creation, token acquisition and credential management.

Custom Device configuration and data input use different authentication paths. Data Source and Data Parser management use your user access token; HTTP ingestion requires a Client Credential token. MQTT uses separate device Broker credentials.

A user first creates the credential; the integration then uses the returned clientId and clientSecret to request its M2M token.

Use the APIs in this guide to create and manage credentials. WEDA Console does not provide Client Credential management in this release.

For Custom Device HTTP ingestion, prepare:

• Credential management access: A user account permitted to create Client Credentials, with a WEDA user access token. User Authentication explains how to obtain that token.
• Target device: An existing Custom Device ID for the integration example.
• Ingestion scope: http-server-data.write, specified when creating the credential. Tokens issued for a credential with this scope carry the audience custom-device-api, which the HTTP endpoint also requires.

The steps below use https://weda.example.com and tenant central. Replace them with your environment.

Caution: Protect the client secret

Keep the client secret in the integration environment that uses it, outside publicly served frontend code.

Create a Client Credential

1. Send the create request using your user access token:

   POST https://weda.example.com/central/weda/api/v1/oauth2/client-credentials
   Authorization: Bearer {accessToken}
   Content-Type: application/json
   
   {
     "name": "custom-device-http-ingest",
     "scopes": ["http-server-data.write"],
     "deviceIds": ["your-custom-device-id"]
   }

2. Replace your-custom-device-id with the device ID for your example. Choose the credential settings for your integration:

   • name: Required label for identifying the credential.
   • scopes: Permissions requested by the integration. The example requests HTTP ingestion.
   • deviceIds: Device IDs recorded in the credential configuration and token. See the device-access note below.
   • expiredAt: Optional expiration date-time. If omitted, the credential has no expiration date. Access tokens have their own lifetime.

3. Retain the returned clientCredentialId, clientId and clientSecret. Use the credential ID for management and the client ID / secret for token acquisition.

Check the result: The API returns 201 Created with the credential details. Save the client ID and secret now. The clientSecret is returned only when the credential is created and cannot be retrieved through another API.

Note: Device IDs do not restrict access

In v1.2.0, deviceIds is recorded in the token but is not checked to restrict access to those devices. Including one Device ID does not limit the token to that device.

See Create a Client Credential for the request and response fields. Choose the scopes required by the API your integration calls.

Choose scopes for your integration

You can combine scopes in one credential. The following table covers the confirmed data operations used by these guides:

Integration task	Scope
Submit Custom Device data and upload its blob content through HTTP	http-server-data.write
Read latest values, historical values or aggregated values	data-stream.read
Read blob content or blob metadata	blob.read
Read a structured Data Pack record	data-pack.read

Get an M2M Access Token

Send the client ID and secret to Identity, using form encoding:

POST https://weda.example.com/identity/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={clientId}&client_secret={clientSecret}

1. Use the clientId and clientSecret returned by credential creation.
2. Submit the form fields above to the Identity endpoint. The scope form field is optional. If omitted, the token receives the scopes configured when the credential was created.
3. Read access_token from the response and use it in the integration's requests.

Check the result: Identity returns an access_token. This response field uses an underscore; the WEDA user-token endpoint returns accessToken instead.

For example, use the M2M token with the Custom Device HTTP ingestion endpoint:

POST https://weda.example.com/central/weda/api/v1/devices/{deviceId}/data-source/http-server/data?channel={channel}
Authorization: Bearer {m2mAccessToken}

Here, {m2mAccessToken} means the value returned in access_token, and {channel} selects the Data Parser channel configured for the device. The request body depends on the configured Data Source and Parser. Custom Device Integration supplies the data setup, activation, payload and verification steps; this header alone is not a complete ingestion request.

Use the token lifetime returned by Identity. When a new token is needed, request one using the credential; keep this path separate from the user-token refresh flow.

Manage Client Credentials

Use your user access token for credential management:

Operation	Request	Expected result
List credentials	GET /api/v1/oauth2/client-credentials	200 OK, with credential metadata. The list does not contain clientSecret.
Delete a credential	DELETE /api/v1/oauth2/client-credentials/{clientCredentialId}	204 No Content. Use the credential ID returned by creation, not the client ID.

Prefix these paths with your environment's WEDA base, such as https://weda.example.com/central/weda. See List Client Credentials and Delete a Client Credential.

Replace a credential

If you lose the secret or need to replace it:

1. Create a new Client Credential and save its client ID and secret.
2. Update the integration to use the new credential, request a token and confirm its API requests succeed.
3. Delete the old credential using its clientCredentialId.

Note: Issued tokens have a deletion delay

Previously issued access tokens are invalidated 15 minutes after credential deletion. The delay starts when you delete the credential, so deletion does not immediately block existing tokens.

Troubleshooting

What you see	What to check
User-token API requests work, but Custom Device HTTP ingestion fails	Use the Client Credential token from Identity. The ingestion endpoint requires audience custom-device-api and scope http-server-data.write; a user token is not a substitute.
The M2M token request fails	Check the Identity URL, grant_type=client_credentials, form encoding, client ID and secret. Check whether the credential has expired or been deleted.
Your client cannot find the M2M token in the response	Read Identity's access_token field rather than the user-token API's accessToken field.
You lost the client secret	It cannot be retrieved again. Create a replacement credential and update the integration before deleting the old credential.