Skip to content

App Clients

App clients are the machine-to-machine (M2M) credentials your programs use to authenticate. Each is a client id and client secret pair that belongs to one organization. A subscription belongs to the app client that created it, which is why an app client that still has subscriptions cannot be deleted. See Identity & Access.

Endpoints

Method Path Permission Purpose
GET /apps?organizationId=<org> app_clients:read List the organization's app clients. Never returns a secret.
POST /apps app_clients:write Create an app client. The response carries its secret.
PUT /apps/{id} app_clients:write Rename an app client. The name is the only thing you can change.
GET /apps/{id}/credentials app_clients:write Read one app client's client id and secret again.
DELETE /apps/{id} app_clients:delete Delete an app client. Refused while it still has subscriptions.

{id} is either the id from the list or the app client's client id; both work.

A member needs the permission in the organization's role. An app client's own token reaches the first four endpoints through appclients/read:all and appclients/write:all. None of the scopes an app client can be given grants app_clients:delete, so only a member can delete an app client. See Authentication.

Create an app client

POST /apps with { "organizationId": "<org>", "name": "<name>", "scopes": [ ... ] }.

  • name is required: up to 128 characters, made of letters, digits, spaces, _ and -, and starting with a letter or digit. Names in the form template-<slug>-publisher are reserved for template publisher credentials and refused.
  • scopes is optional. Leave it out, or send an empty list, and the app client gets the whole set listed under Authentication: Scopes; the portal always does this. You can ask for fewer, but not for anything else: a scope outside the set answers 400 ("Unknown scope(s): …"). The set holds a single event-stream scope, rabbitmq/read:all, so an app client can consume from its delivery queues and do nothing else on the stream. Scopes cannot be changed after creation.
  • Token lifetimes are set by the platform, not by the request: access and ID tokens last 60 minutes, refresh tokens one day.

The answer is 201 with the new app client, including clientSecret.

List app clients

GET /apps?organizationId=<org> answers { "organizationId": "<org>", "apps": [ ... ], "count": N }, newest first. The list is not paged. Each row carries id, appClientId (the client id), clientName, clientKind (app, or template_publisher), processorTemplateId, isActive, createdAt and updatedAt. clientSecret is always null in the list.

Two options add to each row:

Parameter Adds
includeSubscriptionCounts=true subscriptionCount: how many subscriptions the app client has that are not deleted, whether pending, active or error. Deleting the app client is refused on this same count.
includeCognitoDetails=true The token lifetimes (accessTokenExpiration, idTokenExpiration, refreshTokenExpiration, authenticationFlowSessionDuration) and enableTokenRevocation, plus detailsUnavailable. When detailsUnavailable is true, those details could not be read at that moment, and their null values do not mean "unset".

A credential's subscriptions

Subscriptions are listed per app client with GET /subscriptions:

  • The app client itself sends no parameters and gets the subscriptions it created (subscriptions/read:self).
  • A member with subscriptions:read passes ?organizationId=<org>&appClientId=<client>, where <client> is either the app client's id or its client id. An app client from another organization answers 404.

The answer lists every subscription that is not deleted, newest first:

Status Meaning
pending Accepted; the platform is still setting it up.
active Set up. Its coverage report may still be empty.
error It could not be set up. lastErrorCode says why.

Every row carries lastErrorCode. On an error row it is one of the codes below; on every other row it is null. The API returns only the code, never the underlying diagnostic. The remedy is the same for every code: delete the subscription and subscribe again.

lastErrorCode What happened
BROKER_REFUSED The message broker refused a request while setting the subscription up, so retrying cannot fix it.
PROVISIONING_FAILED Setup kept failing on temporary problems until it ran out of attempts.
QUEUE_ORPHANED When the subscription was made, its delivery queue could be neither created nor removed.
LEGACY_RESUBSCRIBE The subscription was created before the current delivery system.

A subscription leaves the list as soon as its delete is accepted (202). Each row carries its coverage report, but not the lens alias; read one subscription with GET /subscriptions/{id} for that. See Subscriptions: list subscriptions and Error codes.

Delete an app client

DELETE /apps/{id} is refused while the app client still has any subscription that is not deleted. That rule means a subscription is never left without an owner: nobody could list it, and its queue and processors would keep running.

The checks run in this order:

The app client… Answer
does not exist, or has already been deleted 404 "App client was not found"
exists, but the caller lacks app_clients:delete 403
is a template publisher credential 409 "Template publisher credentials cannot be deleted independently of their template"
still has subscriptions that are pending, active or error 409 "App client still has N active subscription(s); delete them before deleting the app client"
has none 200 { "message": "App client deleted successfully", "app": { ... }, "cognitoDeleted": true }

The count includes pending and error subscriptions

The 409 sentence says "active", but N counts every subscription that is not deleted, the same number includeSubscriptionCounts shows. A refused delete changes nothing: the credential keeps working and its subscriptions keep running.

To get past the refusal, delete each of the app client's subscriptions with DELETE /subscriptions/{id}. A subscription stops counting the moment its delete is accepted with 202, so you can delete the app client right after. Delivery stops when the delete is accepted, and the platform releases the processors in the background. The app client can do this itself with subscriptions/delete:self. If its program is gone, a member with subscriptions:delete can do it. In the portal, the app client's Subscriptions section has a delete control on each row. See Delete a subscription.

cognitoDeleted is false only when the credential had already been removed from the sign-in service; the app client is deleted either way.

The secret

The create response carries the secret, and a caller with app_clients:write can read it again with GET /apps/{id}/credentials. The answer is { "id", "appClientId", "clientName", "clientKind", "clientSecret" }. Anyone with that permission could create an equivalent credential anyway, so revealing an existing one grants nothing new. app_clients:read never reaches a secret.

A secret cannot be changed. To rotate one:

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

Template publisher credentials

The list also shows the credential each processor template publishes with (clientKind: "template_publisher", with its processorTemplateId). Such a credential is created with its template and lives as long as the template does:

  • It cannot be created through POST /apps: the reserved name is refused, and so is a templateProcessorSlug field (400).
  • It cannot be renamed (409 "Template publisher credentials cannot be renamed") or deleted on its own (409).
  • Reading its secret needs processor_template_versions:write as well as app_clients:write.

See the Template Developer Guide.