App Clients¶
App clients are the machine-to-machine (M2M) credentials your programs use to authenticate, for example with the Application SDK. Each one is a client ID and client secret pair that belongs to your organization. Manage them on the App Clients page. You need app_clients:read to see the page.
A subscription belongs to the app client whose credentials created it. The portal doesn't create subscriptions. Each app client's dialog lists the ones it holds, and lets you delete them.
The app clients list¶
The list shows each app client's Name, Client ID, Subscriptions (how many subscriptions it holds that haven't been deleted) and Created date, newest first. The column picker adds Updated and the token settings: Access token, ID token, Refresh token, Auth session and Token revocation. Search by name or client ID. Lists work as described in Working with lists.
- Subscriptions is counted after the rows load, so the cell pulses briefly. If the count can't be read, it shows "Couldn't count subscriptions" instead of a number. You can't sort by this column.
- Details unavailable under a name means the token settings couldn't be read at that moment. Their empty cells don't mean "unset".
- A processor template's publisher credential isn't listed here. It is created and deleted with its template. See the Template developer guide.
To open an app client, click its row or the Open button at the end of the row.
Creating an app client¶
You need app_clients:write.
- Choose Create app client.
- Enter a name: up to 128 characters, using letters, numbers, spaces, underscores and hyphens, and starting with a letter or number.
- Choose Create app client. The dialog shows the new Client ID and Client secret, each with a copy button.
Use the credentials with the SDK or the API:
You can read the secret again later from the app client's dialog. See Application SDK: authentication and API: authentication.
Scopes and token lifetimes¶
The portal asks only for a name. Every app client it creates holds the full set of scopes an app client can have, which includes everything the Application SDK asks for: see API: scopes. The platform sets the token lifetimes: access and ID tokens last 60 minutes, refresh tokens one day. Neither can be changed after creation.
An app client's dialog¶
The dialog has two sections, Details and Subscriptions, listed down its left side. The Subscriptions entry shows how many subscriptions the app client holds.
Details¶
- App client name. With
app_clients:writeyou can rename the app client here. A save bar appears once the name differs from the saved one. Renaming changes only the display name. The client ID and secret stay the same. - Client ID, with a copy button.
- Client secret. With
app_clients:write, choose Show client secret to load it. The secret stays masked on screen, and the copy button puts it on your clipboard. - Token settings and Advanced authentication settings show the token lifetimes and whether token revocation is enabled. They are read-only.
- Timestamps: when the app client was created and last updated.
- Delete app client, at the bottom, with
app_clients:delete. See Deleting an app client.
Subscriptions¶
This section lists the subscriptions created with the app client's credentials, newest first. Listing them needs subscriptions:read. The list refreshes itself every 5 seconds while the section is open. Use Pause auto-refresh to stop that, or Refresh to reload at once.
Each subscription shows its name, its delivery queue, its status, when it was activated and how many sensors it uses. Every subscription that hasn't been deleted is listed, whatever its status:
| Status | Meaning |
|---|---|
| Pending | Accepted. The platform is still setting it up. |
| Active | Set up. Some of its event types may not be covered yet (see below). |
| Error | It could not be set up. The row says why. |
When a subscription is in error¶
An Error subscription shows a plain explanation. The remedy is always the same: delete the subscription and subscribe again.
| The row says | What happened | Code the API and SDK report |
|---|---|---|
| Couldn't set up this subscription: "The platform couldn't set up this subscription. Delete it and try again; if it keeps failing, contact support with this ID." The row also shows the Subscription ID, with a copy button. | The platform refused, or kept failing, to set it up. | BROKER_REFUSED, PROVISIONING_FAILED |
| This subscription needs to be recreated: "Delete this subscription and subscribe again." | Its delivery queue couldn't be set up when it was created. | QUEUE_ORPHANED |
| This subscription needs to be recreated: "It was created before the current delivery system. Delete this subscription and subscribe again." | It predates the current delivery system. | LEGACY_RESUBSCRIBE |
The portal never shows the platform's internal diagnostic text, only this explanation. The same codes are described in API: error codes.
Event types that aren't covered¶
A subscription can be Active while some of its event types have nothing producing them. Such a row lists them under Not covered, each with a reason:
| Reason | Where to fix it |
|---|---|
| The lens is no longer shared with you | Lenses |
| No sensors cover this area | Sensors |
| No template in this lens produces this event type | Lenses |
| No sensor here can run a template that produces it | Sensors |
When your role can open that page, the reason links to it. Coverage is checked again every hour, so a row can become covered without anyone touching the subscription. See The coverage report.
Deleting a subscription¶
With subscriptions:delete, each row has a delete button. You can delete any of your organization's subscriptions this way, whichever app client created it, which also covers a program whose secret is lost.
- Choose the delete button on the row.
- Confirm Delete subscription.
The platform accepts the delete straight away. The subscription's delivery queue is removed, so any program still reading it stops receiving events. The processors that nothing else uses are released shortly afterwards. The row disappears from the list as soon as the delete is accepted. It can't be undone. To receive those events again, subscribe again.
A program can also delete its own subscriptions. See Application SDK: delete a subscription.
Deleting an app client¶
Delete app client is at the bottom of the Details section, for members with app_clients:delete.
- While the app client holds subscriptions, Delete is disabled. It says "Delete this app client's n subscriptions first." and offers Go to Subscriptions. Pending and error subscriptions count too. Delete them first.
- Otherwise, type the app client's name to confirm. Programs that authenticate with its client ID and secret stop working, and its credentials are revoked. This can't be undone.
If a program creates a subscription while you are confirming, the platform refuses the delete, the dialog says why, and closing it takes you to the Subscriptions section.
Reload after clearing subscriptions
The Subscriptions column, and the check behind Delete app client, use the count taken when the page loaded. If Delete still asks you to delete subscriptions after you've removed them all, reload the page.
Rotating a secret¶
A secret can't be changed. To rotate one:
- Create a new app client.
- Move your program over to the new credentials.
- Subscribe again with the new credentials. A subscription stays with the app client that created it and can't be moved.
- Delete the old app client's subscriptions, then the old app client.