---
title: "Create or update Applications from ApplicationSpec"
method: PUT
path: "/organizations/{orgId}/environments/{envId}/applications"
tags: ["Applications"]
---

# Create or update Applications from ApplicationSpec

`PUT /organizations/{orgId}/environments/{envId}/applications`

Create/update Applications from Application Spec

## Path parameters

- `orgId` string, required
- `envId` string, required

## Query parameters

- `dryRun` boolean

## Request body

- ApplicationSpec — Defines the desired state of Application. It represents an API consumer. Applications act on behalf of users to request tokens, provide user identity information, and access protected resources from APIs. They can be of different types, such as Simple, Web, SPA, Native, or Backend-to-backend, each with specific configuration requirements. Applications are also used to manage API keys, analytics, and subscriptions.
  - `hrid` string, required — A unique human readable id identifying this resource
  - `name` string, required — Application's name. Duplicate names can exists.
  - `description` string, required — This is where you can clearly state the API’s purpose and what problems it solves to help drive API discovery and adoption by making it easier for developers to find and understand the API’s capabilities.
  - `domain` string — Application's domain.
  - `groups` string[] — List of groups associated with the Application. This groups are names, HRIDs or UUIDs of existing groups in APIM.
  - `pictureUrl` string — Application's picture Url.
  - `notifyMembers` boolean — If true, new members added to the Application spec will be notified when the Application is synced with APIM.
  - `background` string — Application's background url
  - `primaryOwner` PrimaryOwner — User owner of this. Can perform all possible actions on it.
    - `id` string — Owner's uuid.
    - `email` string — Owner's email. Can be null if owner is a group.
    - `displayName` string — Owner's name.
    - `type` 'USER' | 'GROUP' — The type of membership
  - `settings` ApplicationSettings — Application settings defines the configuration of consumers authentication. Depending on the control plane configuration some applications types may be restricted. `app` and `oauth` are mutually exclusive. If none is set it fallbacks to `app` without any property set.
    - `app` SimpleApplicationSettings — Simple application settings
      - `type` string — Simple application type, for information
      - `clientId` string — Simple application client ID
    - `oauth` ApplicationOAuthClientSettings — Application OAuth client settings. This require Dynamic Client Registration to be enabled at the environment level.
      - `applicationType` 'browser' | 'web' | 'native' | 'backend_to_backend', required — OAuth client application type: `browser` for single page apps (SPA), `web` for regular web apps, `native` for smartphone apps, `backend_to_backend` for backend to backend.
      - `grantTypes` string[], required — OAuth client grant types. `authorization_code` is mandatory except when application type is `backend_to_backend`. `refresh_token` can be used only application type is `web` and `browser`. `password` (Resource Owner Password) only with applicationType `native`. `client_credentials` only works when application type is `backend_to_backend`
      - `redirectUris` string[], required — OAuth client redirect Uris
      - `additionalClientMetadata` object
    - `tls` ApplicationTLSSettings — Application TLS settings
      - `clientCertificate` string — Application TLS client certificate. Deprecated: use clientCertificates instead for multiple certificate support.
      - `clientCertificates` ClientCertificate[] — List of client certificates for mTLS authentication. Supports certificate rotation.
        - `name` string, required — Certificate name for identification
        - `content` string, required — Certificate in PEM format
        - `startsAt` string, date-time — Date when this certificate becomes active
        - `endsAt` string, date-time — Date when this certificate will be removed
  - `metadata` Metadata[] — The list of Application's metadata.
    - `key` string — The key of the metadata if different from sanitized name (lowercase + hyphens).
    - `name` string, required — The name of the metadata.
    - `format` 'STRING' | 'NUMERIC' | 'BOOLEAN' | 'DATE' | 'MAIL' | 'URL', required — The format of the metadata.
    - `value` string — The value of the metadata.
    - `defaultValue` string — The default value of the metadata if the value is not set.
  - `members` Member[] — Users that can access or manage this application (depending on their roles).
    - `source` string, required — Where the member was created (system, idp, etc.)
    - `sourceId` string, required — Id of the user in the source
    - `role` string, required — The role of the user in regards of the managed object (API, Application, etc.)
  - `status` 'ACTIVE' | 'ARCHIVED' — Application are either ACTIVE or ARCHIVED never actually deleted.

## Response `200`

State of the successfully created/updated Applications

- ApplicationState — Base status properties common to all resources.
  - `hrid` string, required — A unique human readable id identifying this resource
  - `name` string, required — Application's name. Duplicate names can exists.
  - `description` string, required — This is where you can clearly state the API’s purpose and what problems it solves to help drive API discovery and adoption by making it easier for developers to find and understand the API’s capabilities.
  - `domain` string — Application's domain.
  - `groups` string[] — List of groups associated with the Application. This groups are names, HRIDs or UUIDs of existing groups in APIM.
  - `pictureUrl` string — Application's picture Url.
  - `notifyMembers` boolean — If true, new members added to the Application spec will be notified when the Application is synced with APIM.
  - `background` string — Application's background url
  - `primaryOwner` PrimaryOwner — User owner of this. Can perform all possible actions on it.
    - `id` string — Owner's uuid.
    - `email` string — Owner's email. Can be null if owner is a group.
    - `displayName` string — Owner's name.
    - `type` 'USER' | 'GROUP' — The type of membership
  - `settings` ApplicationSettings — Application settings defines the configuration of consumers authentication. Depending on the control plane configuration some applications types may be restricted. `app` and `oauth` are mutually exclusive. If none is set it fallbacks to `app` without any property set.
    - `app` SimpleApplicationSettings — Simple application settings
      - `type` string — Simple application type, for information
      - `clientId` string — Simple application client ID
    - `oauth` ApplicationOAuthClientSettings — Application OAuth client settings. This require Dynamic Client Registration to be enabled at the environment level.
      - `applicationType` 'browser' | 'web' | 'native' | 'backend_to_backend', required — OAuth client application type: `browser` for single page apps (SPA), `web` for regular web apps, `native` for smartphone apps, `backend_to_backend` for backend to backend.
      - `grantTypes` string[], required — OAuth client grant types. `authorization_code` is mandatory except when application type is `backend_to_backend`. `refresh_token` can be used only application type is `web` and `browser`. `password` (Resource Owner Password) only with applicationType `native`. `client_credentials` only works when application type is `backend_to_backend`
      - `redirectUris` string[], required — OAuth client redirect Uris
      - `additionalClientMetadata` object
    - `tls` ApplicationTLSSettings — Application TLS settings
      - `clientCertificate` string — Application TLS client certificate. Deprecated: use clientCertificates instead for multiple certificate support.
      - `clientCertificates` ClientCertificate[] — List of client certificates for mTLS authentication. Supports certificate rotation.
        - `name` string, required — Certificate name for identification
        - `content` string, required — Certificate in PEM format
        - `startsAt` string, date-time — Date when this certificate becomes active
        - `endsAt` string, date-time — Date when this certificate will be removed
  - `metadata` Metadata[] — The list of Application's metadata.
    - `key` string — The key of the metadata if different from sanitized name (lowercase + hyphens).
    - `name` string, required — The name of the metadata.
    - `format` 'STRING' | 'NUMERIC' | 'BOOLEAN' | 'DATE' | 'MAIL' | 'URL', required — The format of the metadata.
    - `value` string — The value of the metadata.
    - `defaultValue` string — The default value of the metadata if the value is not set.
  - `members` Member[] — Users that can access or manage this application (depending on their roles).
    - `source` string, required — Where the member was created (system, idp, etc.)
    - `sourceId` string, required — Id of the user in the source
    - `role` string, required — The role of the user in regards of the managed object (API, Application, etc.)
  - `status` 'ACTIVE' | 'ARCHIVED' — Application are either ACTIVE or ARCHIVED never actually deleted.
  - `id` string — Resource UUID.
  - `environmentId` string — The environment ID.
  - `organizationId` string — The organization ID.
  - `errors` Errors — When a resource has been created regardless of errors, this field is used to persist the error message encountered during validation
    - `severe` string[] — Severe errors do not pass validation and will block creation/update/delete hence, this field should always be populated during the validation phase and is very unlikely to be persisted client side.
    - `warning` string[] — Warning errors do not block object creation/update/delete, most of the time because the value is ignored or defaulted.

## Other responses

- `400` — Request is invalid
- `401` — Unauthenticated
- `403` — Unauthorized
- `404` — Resource not found
- `default` — Default error

---

[API](https://skmtc.net/gravitee-io/apis/gravitee-io-automation-api.md) · [All operations](https://skmtc.net/gravitee-io/apis/gravitee-io-automation-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gravitee-io/gravitee-io-automation-api/revisions/ecefec7d65f9/schema)