Skip to content

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.

  1. Choose Create app client.
  2. Enter a name: up to 128 characters, using letters, numbers, spaces, underscores and hyphens, and starting with a letter or number.
  3. 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:

export DORY_CLIENT_ID="<client id>"
export DORY_CLIENT_SECRET="<client secret>"

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:write you 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.

  1. Choose the delete button on the row.
  2. 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:

  1. Create a new app client.
  2. Move your program over to the new credentials.
  3. Subscribe again with the new credentials. A subscription stays with the app client that created it and can't be moved.
  4. Delete the old app client's subscriptions, then the old app client.