# Upsert applications

URL: https://docs.hanzo.ai/docs/openapi/iam/upsertapplication

> Creates an application or updates it in place, so a deployment can declare the applications it needs and run the same declaration on every environment and on every redeploy.

`POST /v1/iam/admin/applications/upsert`

> [IAM →](https://docs.hanzo.ai/docs/openapi/iam) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                                         |
| ------------- | ------------------------------------------------------- |
| **Address**   | `https://api.hanzo.ai/v1/iam/admin/applications/upsert` |
| **Method**    | `POST`                                                  |
| **Operation** | `upsertApplication`                                     |
| **Auth**      | `Authorization: Bearer $HANZO_API_KEY`                  |

Creates an application or updates it in place, so a
deployment can declare the applications it needs and run the same declaration
on every environment and on every redeploy.

It says which of the two it did. Leave the client secret out and the existing
one is kept — so re-running your deployment does not rotate a credential your
running services are holding.

## Request

14 fields, body `application/json` (required).

| Field                  | In     | Type            | Required | Description                                                                                                |
| ---------------------- | ------ | --------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `Authorization`        | header | string          | —        |                                                                                                            |
| `cert`                 | body   | string          | —        |                                                                                                            |
| `clientId`             | body   | string          | —        |                                                                                                            |
| `clientSecret`         | body   | string          | —        |                                                                                                            |
| `displayName`          | body   | string          | —        |                                                                                                            |
| `enableCodeSignin`     | body   | boolean         | —        | EnableCodeSignin offers sign-in by an emailed or texted one-time code beside the password.                 |
| `expireInHours`        | body   | number (double) | —        | ExpireInHours and RefreshExpireInHours are the application's token lifetimes.                              |
| `grantTypes`           | body   | string\[]       | —        |                                                                                                            |
| `isShared`             | body   | boolean         | —        | IsShared declares that this application serves EVERY organization, not only the one named in Organization. |
| `name`                 | body   | string          | —        |                                                                                                            |
| `organization`         | body   | string          | —        |                                                                                                            |
| `public`               | body   | boolean         | —        | Public declares a client that CANNOT hold a credential — a browser SPA, a CLI, a desktop app.              |
| `redirectUris`         | body   | string\[]       | —        |                                                                                                            |
| `refreshExpireInHours` | body   | number (double) | —        |                                                                                                            |

## Response

| Status    | Body            | Meaning               |
| --------- | --------------- | --------------------- |
| `200`     | iam.reply       | ok                    |
| `400`     | iam.reply       | bad request           |
| `401`     | iam.reply       | unauthorized          |
| `409`     | iam.reply       | conflict              |
| `500`     | iam.reply       | internal server error |
| `default` | problem-details | refused               |

`200` body — 4 fields.

| Field    | In   | Type   | Always | Description |
| -------- | ---- | ------ | ------ | ----------- |
| `action` | body | string | —      |             |
| `data`   | body | any    | —      |             |
| `msg`    | body | string | —      |             |
| `status` | body | string | —      |             |

Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo iam admin applications upsert
```

**SDK**

**.ts**

```ts
import { Configuration, IamApi } from 'hanzoai';

const api = new IamApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.upsertApplication({ cert: "<cert>", clientId: "<clientId>" });
```

**.py**

```python
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import IamApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = IamApi(client).upsert_application(cert="<cert>", client_id="<clientId>")
```

**.go**

```go
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.IamAPI.UpsertApplication(context.Background()).Execute()
if err != nil {
	return err
}
```

**.rs**

```rust
use hanzo_client::apis::{configuration::Configuration, iam_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = iam_api::upsert_application(&cfg, Default::default()).await?;
```

**.java**

```java
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.IamApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new IamApi(client).upsertApplication();
```

**HTTP**

```bash
curl -X POST https://api.hanzo.ai/v1/iam/admin/applications/upsert \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "cert": "<cert>",
       "clientId": "<clientId>"
     }'
```

**MCP**

Tool `iam`, op `upsertApplication` — POST the JSON-RPC envelope to `https://api.hanzo.ai/v1/mcp`.

```bash
curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "iam",
         "arguments": {
           "op": "upsertApplication",
           "input": {
             "cert": "<cert>",
             "clientId": "<clientId>"
           }
         }
       }
     }'
```

---

[IAM API](https://docs.hanzo.ai/docs/openapi/iam) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)