# Update an app identity

`PATCH /apis/cra.diagrid.io/v1beta1/projects/{ProjectId}/appids/{ProjectSubresourceId}`

Partially update an existing app identity.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `ProjectId` | string | Yes | Unique identifier of the project. |
| `ProjectSubresourceId` | string | Yes | Unique identifier of the project subresource. |

### Request body

The app identity fields to update.

`application/json`

- `apiVersion` (string)
- `kind` (string)
- `metadata` (object)
  - `name` (string)
  - `uid` (string)
  - `resourceVersion` (integer)
  - `createdAt` (string)
  - `updatedAt` (string)
  - `deletedAt` (string)
  - `labels` (object<string, string>)
  - `annotations` (object)
- `spec` (object) — Required. AppIdentitySpec is the user-facing specification of an App ID.
  - `projectId` (string) — Required. Read-only. Immutable. ProjectID is server-derived from the request path; the client-supplied value is ignored.
  - `apiTokenRevision` (integer)
  - `appEndpoint` (object) — AppEndpoint is the application endpoint configuration of an App ID.
    - `url` (string)
    - `clientTimeoutSeconds` (integer)
    - `token` (string) — Write-only. Token authenticates calls from the dataplane to the app endpoint. It can only be written: responses never include it, the app token is only returned as .status.appToken.
  - `healthCheck` (object)
    - `path` (string) — used for HTTP e.g. /health.
    - `probe` (object)
      - `enabled` (boolean)
      - `intervalInSec` (integer (int32))
      - `timeoutInMs` (integer (int32))
      - `failureThreshold` (integer (int32))
  - `protocol` (string)
  - `appConfig` (string)
  - `resiliency` (object)
    - `retryPolicyName` (string)
    - `timeoutPolicyName` (string)
    - `circuitBreakerPolicyName` (string)
  - `maxBodySize` (string)
  - `external` (boolean) — Immutable.
  - `appContainer` (object) — AppContainerSpec holds configuration for an app container that runs alongside a sidecar.
    - `image` (string)
    - `port` (integer)
    - `pullPolicy` (string)
    - `command` (string[])
    - `args` (string[])
    - `env` (object<string, string>)
    - `files` (object<string, string>)
  - `workflowArchive` (object) — WorkflowArchiveSpec selects which terminal workflow states have their history archived on purge and where the archive is written. Archiving is enabled when a destination binding is set.
    - `completed` (boolean) — Completed archives workflows that reach the Completed terminal state.
    - `failed` (boolean) — Failed archives workflows that reach the Failed terminal state.
    - `terminated` (boolean) — Terminated archives workflows that reach the Terminated terminal state.
    - `destination` (object) — WorkflowArchiveDestination identifies the archive output binding.
      - `binding` (string) — Binding is the output-binding component name. Empty disables archiving.
      - `type` (string) — Type is the binding component type (e.g. "bindings.aws.s3").
  - `workflowNotifications` (object) — WorkflowNotificationsSpec selects which workflow outcomes raise an alert. Completed workflows are not selectable: the policy reports outcomes that need someone's attention.
    - `name` (string) — Name is a regular expression the workflow name must match in full. Empty matches every workflow.
    - `failed` (boolean) — Failed notifies workflows that reach the Failed terminal state.
    - `terminated` (boolean) — Terminated notifies workflows that reach the Terminated terminal state.
    - `stalled` (boolean) — Stalled notifies workflows that reach the Stalled state.
    - `rootOnly` (boolean) — RootOnly restricts notifications to workflows with no parent, so one failing parent does not also alert for each of its children.
- `status` (object) — AppIdentityStatus represents the status of an application identity.
  - `status` (string) — Status is the current processing status of the resource.
  - `updatedAt` (string) — UpdatedAt is the time of the last status update.
  - `messages` (object[]) — Messages contains any status messages, such as error details.
    - `message` (string)
  - `instances` (object[]) — Instances includes the status for each instance of the resource.
    - `cluster` (string) — Cluster is the name of the cluster hosting this instance.
    - `region` (string) — Region is the region where the instance is located (e.g. "us-east-1").
    - `placementId` (string) — PlacementID is the project placement this instance belongs to (e.g. "1").
    - `status` (string) — Status is the current processing status of the resource.
    - `updatedAt` (string) — UpdatedAt is the time of the last status update.
    - `messages` (object[]) — Messages contains any status messages, such as error details.
      - `message` (string)
  - `apiToken` (string) — APIToken is omitted unless the caller has the appIdCredentials.get permission.
  - `appToken` (string)
  - `resiliencyStatus` (object)
    - `retryPolicyName` (string)
    - `timeoutPolicyName` (string)
    - `circuitBreakerPolicyName` (string)
  - `resiliency` (object)
    - `projectId` (string) — Required. Immutable.
    - `resiliencySpec` (object) — Required. ResiliencySpec is the Dapr resiliency specification (policies and targets), based on the upstream Dapr Resiliency API. Fields present upstream but not listed here are not supported in Catalyst.
      - `policies` (object)
        - `timeouts` (object<string, string>)
        - `retries` (object<string, object>)
          - `policy` (string)
          - `duration` (string)
          - `maxInterval` (string)
          - `maxRetries` (integer)
          - `matching` (object) — RetryMatching specifies which status codes should trigger a retry. When set, only matching errors are retried; unmatched errors (e.g. 403) fail immediately instead of being retried into a timeout.
            - `httpStatusCodes` (string)
            - `gRPCStatusCodes` (string)
        - `circuitBreakers` (object<string, object>)
          - `maxRequests` (integer)
          - `interval` (string)
          - `timeout` (string)
          - `trip` (string)
      - `targets` (object)
        - `apps` (object<string, object>)
          - `timeout` (string)
          - `retry` (string)
          - `circuitBreaker` (string)
          - `circuitBreakerCacheSize` (integer)
        - `components` (object<string, object>)
          - `inbound` (object)
            - `timeout` (string)
            - `retry` (string)
            - `circuitBreaker` (string)
          - `outbound` (object)
            - `timeout` (string)
            - `retry` (string)
            - `circuitBreaker` (string)
    - `scopes` (string[])
  - `spiffeId` (string) — SpiffeID is the single workload identity this App ID is reported under: the identity it is issued in the first of its project's regions by name. It does not move when a region is promoted, and a workload running in any other region of the project presents a different identity. Use regionIdentities to pre-trust the identity of every region instead of following this one.
  - `spiffeIds` (string[]) — SpiffeIDs is every workload identity this App ID is issued, one per region its project is placed in, in the same order as regionIdentities. Deprecated: use regionIdentities instead, which names the region each identity belongs to.
  - `regionIdentities` (object[]) — RegionIdentities lists the workload identity this App ID is issued in every region its project is placed in, one entry per region, ordered by region name. It is spiffeIds with the region each identity belongs to named, so a reader does not have to take it from the trust domain. Pre-trust every entry in an external identity federation: a project spread over a region group runs under a different identity in each of its regions, and which one a workload presents follows the region it runs in. The OIDC issuer that verifies JWTs minted for an identity is the region's, and is read from that region (status.endpoints.oidc).
    - `region` (string) — Region is the region the identity is issued in. Read that region to get the OIDC issuer verifying JWTs minted for this identity, and the trust anchors verifying its certificates: both are region properties, served on the region's own status.endpoints.
    - `spiffeId` (string) — SpiffeID is the SPIFFE ID workloads of this App ID present in that region.
  - `externalBootstrapConfig` (string) — ExternalBootstrapConfig is the bootstrap YAML configuration for external appIDs. It contains everything an external workload needs to connect to the data plane, including the required endpoints and the join token.
  - `isActive` (boolean) — IsActive indicates if the app identity is active, if the sidecar has performed API operations recently.
  - `workflowsConnected` (boolean) — WorkflowsConnected indicates if the app identity has workflow workers currently connected.
  - `clientType` (string) — ClientType is the identity-view classification of this App ID — "app", "agent", or "mcpserver".
  - `appEndpointStatus` (string) — Deprecated: use appHealthCheckStatus instead.
  - `appHealthCheckStatus` (object) — AppIdentityAppHealthCheckStatus represents the health check status of an application identity.
    - `ishealthy` (boolean)
    - `timestamp` (string)
    - `reason` (string)
  - `events` (object) — AppIdentityEvents represents events from an application identity.
    - `errors` (object[])
      - `cluster` (string) — Cluster is the name of the cluster the event originated from.
      - `message` (string)
      - `timestamp` (string (date-time))

Example:

```json
{
  "apiVersion": "cra.diagrid.io/v1beta1",
  "kind": "AppIdentity",
  "metadata": {
    "name": "order-api"
  },
  "spec": {
    "projectId": "my-project",
    "appEndpoint": {
      "url": "https://orders.example.com",
      "token": "<app-token>"
    },
    "protocol": "http"
  }
}
```

`application/vnd.api+json`

JSONAPI.org specification app identity response wrapper for UI.

- `data` (object) — Required.
  - `type` (string) — Type of the resource object.
  - `id` (string) — Unique identifier of the resource object.
  - `attributes` (object)
    - `apiVersion` (string)
    - `kind` (string)
    - `metadata` (object)
      - `name` (string)
      - `uid` (string)
      - `resourceVersion` (integer)
      - `createdAt` (string)
      - `updatedAt` (string)
      - `deletedAt` (string)
      - `labels` (object<string, string>)
      - `annotations` (object)
    - `spec` (object) — Required. AppIdentitySpec is the user-facing specification of an App ID.
      - `projectId` (string) — Required. Read-only. Immutable. ProjectID is server-derived from the request path; the client-supplied value is ignored.
      - `apiTokenRevision` (integer)
      - `appEndpoint` (object) — AppEndpoint is the application endpoint configuration of an App ID.
        - `url` (string)
        - `clientTimeoutSeconds` (integer)
        - `token` (string) — Write-only. Token authenticates calls from the dataplane to the app endpoint. It can only be written: responses never include it, the app token is only returned as .status.appToken.
      - `healthCheck` (object)
        - `path` (string) — used for HTTP e.g. /health.
        - `probe` (object)
          - `enabled` (boolean)
          - `intervalInSec` (integer (int32))
          - `timeoutInMs` (integer (int32))
          - `failureThreshold` (integer (int32))
      - `protocol` (string)
      - `appConfig` (string)
      - `resiliency` (object)
        - `retryPolicyName` (string)
        - `timeoutPolicyName` (string)
        - `circuitBreakerPolicyName` (string)
      - `maxBodySize` (string)
      - `external` (boolean) — Immutable.
      - `appContainer` (object) — AppContainerSpec holds configuration for an app container that runs alongside a sidecar.
        - `image` (string)
        - `port` (integer)
        - `pullPolicy` (string)
        - `command` (string[])
        - `args` (string[])
        - `env` (object<string, string>)
        - `files` (object<string, string>)
      - `workflowArchive` (object) — WorkflowArchiveSpec selects which terminal workflow states have their history archived on purge and where the archive is written. Archiving is enabled when a destination binding is set.
        - `completed` (boolean) — Completed archives workflows that reach the Completed terminal state.
        - `failed` (boolean) — Failed archives workflows that reach the Failed terminal state.
        - `terminated` (boolean) — Terminated archives workflows that reach the Terminated terminal state.
        - `destination` (object) — WorkflowArchiveDestination identifies the archive output binding.
          - `binding` (string) — Binding is the output-binding component name. Empty disables archiving.
          - `type` (string) — Type is the binding component type (e.g. "bindings.aws.s3").
      - `workflowNotifications` (object) — WorkflowNotificationsSpec selects which workflow outcomes raise an alert. Completed workflows are not selectable: the policy reports outcomes that need someone's attention.
        - `name` (string) — Name is a regular expression the workflow name must match in full. Empty matches every workflow.
        - `failed` (boolean) — Failed notifies workflows that reach the Failed terminal state.
        - `terminated` (boolean) — Terminated notifies workflows that reach the Terminated terminal state.
        - `stalled` (boolean) — Stalled notifies workflows that reach the Stalled state.
        - `rootOnly` (boolean) — RootOnly restricts notifications to workflows with no parent, so one failing parent does not also alert for each of its children.
    - `status` (object) — AppIdentityStatus represents the status of an application identity.
      - `status` (string) — Status is the current processing status of the resource.
      - `updatedAt` (string) — UpdatedAt is the time of the last status update.
      - `messages` (object[]) — Messages contains any status messages, such as error details.
        - `message` (string)
      - `instances` (object[]) — Instances includes the status for each instance of the resource.
        - `cluster` (string) — Cluster is the name of the cluster hosting this instance.
        - `region` (string) — Region is the region where the instance is located (e.g. "us-east-1").
        - `placementId` (string) — PlacementID is the project placement this instance belongs to (e.g. "1").
        - `status` (string) — Status is the current processing status of the resource.
        - `updatedAt` (string) — UpdatedAt is the time of the last status update.
        - `messages` (object[]) — Messages contains any status messages, such as error details.
          - `message` (string)
      - `apiToken` (string) — APIToken is omitted unless the caller has the appIdCredentials.get permission.
      - `appToken` (string)
      - `resiliencyStatus` (object)
        - `retryPolicyName` (string)
        - `timeoutPolicyName` (string)
        - `circuitBreakerPolicyName` (string)
      - `resiliency` (object)
        - `projectId` (string) — Required. Immutable.
        - `resiliencySpec` (object) — Required. ResiliencySpec is the Dapr resiliency specification (policies and targets), based on the upstream Dapr Resiliency API. Fields present upstream but not listed here are not supported in Catalyst.
          - `policies` (object)
            - `timeouts` (object<string, string>)
            - `retries` (object<string, object>)
              - `policy` (string)
              - `duration` (string)
              - `maxInterval` (string)
              - `maxRetries` (integer)
              - `matching` (object) — RetryMatching specifies which status codes should trigger a retry. When set, only matching errors are retried; unmatched errors (e.g. 403) fail immediately instead of being retried into a timeout.
                - *(nested fields omitted at this depth)*
            - `circuitBreakers` (object<string, object>)
              - `maxRequests` (integer)
              - `interval` (string)
              - `timeout` (string)
              - `trip` (string)
          - `targets` (object)
            - `apps` (object<string, object>)
              - `timeout` (string)
              - `retry` (string)
              - `circuitBreaker` (string)
              - `circuitBreakerCacheSize` (integer)
            - `components` (object<string, object>)
              - `inbound` (object)
                - *(nested fields omitted at this depth)*
              - `outbound` (object)
                - *(nested fields omitted at this depth)*
        - `scopes` (string[])
      - `spiffeId` (string) — SpiffeID is the single workload identity this App ID is reported under: the identity it is issued in the first of its project's regions by name. It does not move when a region is promoted, and a workload running in any other region of the project presents a different identity. Use regionIdentities to pre-trust the identity of every region instead of following this one.
      - `spiffeIds` (string[]) — SpiffeIDs is every workload identity this App ID is issued, one per region its project is placed in, in the same order as regionIdentities. Deprecated: use regionIdentities instead, which names the region each identity belongs to.
      - `regionIdentities` (object[]) — RegionIdentities lists the workload identity this App ID is issued in every region its project is placed in, one entry per region, ordered by region name. It is spiffeIds with the region each identity belongs to named, so a reader does not have to take it from the trust domain. Pre-trust every entry in an external identity federation: a project spread over a region group runs under a different identity in each of its regions, and which one a workload presents follows the region it runs in. The OIDC issuer that verifies JWTs minted for an identity is the region's, and is read from that region (status.endpoints.oidc).
        - `region` (string) — Region is the region the identity is issued in. Read that region to get the OIDC issuer verifying JWTs minted for this identity, and the trust anchors verifying its certificates: both are region properties, served on the region's own status.endpoints.
        - `spiffeId` (string) — SpiffeID is the SPIFFE ID workloads of this App ID present in that region.
      - `externalBootstrapConfig` (string) — ExternalBootstrapConfig is the bootstrap YAML configuration for external appIDs. It contains everything an external workload needs to connect to the data plane, including the required endpoints and the join token.
      - `isActive` (boolean) — IsActive indicates if the app identity is active, if the sidecar has performed API operations recently.
      - `workflowsConnected` (boolean) — WorkflowsConnected indicates if the app identity has workflow workers currently connected.
      - `clientType` (string) — ClientType is the identity-view classification of this App ID — "app", "agent", or "mcpserver".
      - `appEndpointStatus` (string) — Deprecated: use appHealthCheckStatus instead.
      - `appHealthCheckStatus` (object) — AppIdentityAppHealthCheckStatus represents the health check status of an application identity.
        - `ishealthy` (boolean)
        - `timestamp` (string)
        - `reason` (string)
      - `events` (object) — AppIdentityEvents represents events from an application identity.
        - `errors` (object[])
          - `cluster` (string) — Cluster is the name of the cluster the event originated from.
          - `message` (string)
          - `timestamp` (string (date-time))
  - `relationships` (object<string, object>) — Members of the relationships object represent references from the resource object in which it's defined to other resource objects.
    - Any of:
      - **option 1**
      - **option 2**
      - **option 3**
  - `links` (object<string, object>) — Link members related to the primary data.
    - One of:
      - **string (uri-reference)** — A string containing the link's URL.
      - **object**
        - `href` (string (uri-reference)) — Required. A string containing the link's URL.
        - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.
  - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.
- `links` (object<string, object>) — Link members related to the primary data.
  - One of:
    - **string (uri-reference)** — A string containing the link's URL.
    - **object**
      - `href` (string (uri-reference)) — Required. A string containing the link's URL.
      - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.

## Responses

### 202 — Accepted for asynchronous processing.

### 403 — You are not authorized to perform this action.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

`application/vnd.api+json`

JSONAPI.org specification error response wrapper for UI.

- `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.
  - `code` (string) — Required. This is the same as the HTTP status of the response.
  - `message` (string) — Required. A short description of the error.
  - `status` (object) — Required. A status code that indicates the error type.
  - `details` (object) — Additional details about the errors.
    - `@type` (string) — The type of error.
    - `reason` (string) — A reason for the error.
    - `domain` (string) — The domain in which the error occurred.
    - `metadata` (object) — Additional metadata about the error.
- `meta` (object<string, object>) — Link members related to the primary data.
  - One of:
    - **string (uri-reference)** — A string containing the link's URL.
    - **object**
      - `href` (string (uri-reference)) — Required. A string containing the link's URL.
      - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.
- `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.

### 404 — The app identity was not found.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

`application/vnd.api+json`

JSONAPI.org specification error response wrapper for UI.

- `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.
  - `code` (string) — Required. This is the same as the HTTP status of the response.
  - `message` (string) — Required. A short description of the error.
  - `status` (object) — Required. A status code that indicates the error type.
  - `details` (object) — Additional details about the errors.
    - `@type` (string) — The type of error.
    - `reason` (string) — A reason for the error.
    - `domain` (string) — The domain in which the error occurred.
    - `metadata` (object) — Additional metadata about the error.
- `meta` (object<string, object>) — Link members related to the primary data.
  - One of:
    - **string (uri-reference)** — A string containing the link's URL.
    - **object**
      - `href` (string (uri-reference)) — Required. A string containing the link's URL.
      - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.
- `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.

### 409 — The request conflicts with the current state of the app identity.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

`application/vnd.api+json`

JSONAPI.org specification error response wrapper for UI.

- `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.
  - `code` (string) — Required. This is the same as the HTTP status of the response.
  - `message` (string) — Required. A short description of the error.
  - `status` (object) — Required. A status code that indicates the error type.
  - `details` (object) — Additional details about the errors.
    - `@type` (string) — The type of error.
    - `reason` (string) — A reason for the error.
    - `domain` (string) — The domain in which the error occurred.
    - `metadata` (object) — Additional metadata about the error.
- `meta` (object<string, object>) — Link members related to the primary data.
  - One of:
    - **string (uri-reference)** — A string containing the link's URL.
    - **object**
      - `href` (string (uri-reference)) — Required. A string containing the link's URL.
      - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.
- `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.

### default — Unexpected error.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

`application/vnd.api+json`

JSONAPI.org specification error response wrapper for UI.

- `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.
  - `code` (string) — Required. This is the same as the HTTP status of the response.
  - `message` (string) — Required. A short description of the error.
  - `status` (object) — Required. A status code that indicates the error type.
  - `details` (object) — Additional details about the errors.
    - `@type` (string) — The type of error.
    - `reason` (string) — A reason for the error.
    - `domain` (string) — The domain in which the error occurred.
    - `metadata` (object) — Additional metadata about the error.
- `meta` (object<string, object>) — Link members related to the primary data.
  - One of:
    - **string (uri-reference)** — A string containing the link's URL.
    - **object**
      - `href` (string (uri-reference)) — Required. A string containing the link's URL.
      - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.
- `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.