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": [ ... ] }.
nameis required: up to 128 characters, made of letters, digits, spaces,_and-, and starting with a letter or digit. Names in the formtemplate-<slug>-publisherare reserved for template publisher credentials and refused.scopesis 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 answers400("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:readpasses?organizationId=<org>&appClientId=<client>, where<client>is either the app client'sidor its client id. An app client from another organization answers404.
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:
- Create a new app client.
- Move your program to the new credentials.
- Subscribe again with the new credentials. A subscription stays with the app client that created it and cannot be moved.
- 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 atemplateProcessorSlugfield (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:writeas well asapp_clients:write.
See the Template Developer Guide.