---
title: "configure_push"
description: "Generated reference for the management action configure_push: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/configure-push
order: 59
visibility: public
redirects_from: []
---

# configure\_push

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

A script calls this action over HTTPS at `POST https://tzcloud.turnzero.ai/v1/configure_push`, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool `tzcloud_configure_push`.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts ([Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/)).

**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

## Contract description

Configure or remove Apple and Google push providers for one environment\. First store each credential for that application and environment with `store_secret`\. This call checks its name, never its value\. Your manifest must declare push\. If it lists providers, `submit_manifest` configures them on every environment\. Only Apple's gateway then needs a provider call\. Other changes to manifest\-provided configuration are refused `manifest_owned_field`\.

Delivery needs the accounts service and devices registered after sign\-in\. Configuration takes effect on the next delivery, without a deploy\. Success does not prove the credential works\. After sending, check `read_push` and `read_logs`\.

## More about this action

The `apns` member gives Apple's team and key identifiers, the app's bundle identifier, the gateway \(`production` or `sandbox`\), and the stored signing key's name\. The `fcm` member gives the Firebase project and the stored service\-account file's name\. Each member is optional, and `null` removes that provider\.

An optional `environment` \(`development` or `production`; absent, `production`\) selects which environment your call configures\.

Give at least one provider per call\. Omit a provider to keep it; pass null to remove it\. A provider object must be complete\. To change only the gateway of an Apple provider the manifest supplies, repeat its other four fields unchanged beside `apns.environment`\. When the manifest supplies Apple, its gateway defaults to `sandbox` on development and `production` on production until this call changes it\.

A credential name minted by the platform or bound to an upstream, realm route or setting is refused\. Store a separate credential for this application and environment\. After saving, the platform checks the name again\. If the value was deleted or bound to a setting meanwhile, the configuration is taken back and the call refused\. Delivery alone reads the value; a bad credential can leave configuration accepted but delivery failed\.

## Access and action metadata

```json
{
  "name": "configure_push",
  "resource": "push",
  "tier": "reversible",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "summary": "Set an application environment's push providers — Apple's team, key, bundle, gateway, and stored signing-key name; Google's project and stored service-account file name — each optional, null removing one; refused by name where the manifest declares no push service, where a named secret is not in custody at that scope, or where the name is an upstream's or a realm route's credential or a setting binds it.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": false
  }
}
```

## MCP catalog entry

```json
{
  "name": "configure_push",
  "title": "Configure push notifications",
  "tier": "reversible",
  "summary": "Configure or remove Apple and Google push providers for one environment. First store each credential for that application and environment with `store_secret`. This call checks its name, never its value. Your manifest must declare push. If it lists providers, `submit_manifest` configures them on every environment. Only Apple's gateway then needs a provider call. Other changes to manifest-provided configuration are refused `manifest_owned_field`.\n\nDelivery needs the accounts service and devices registered after sign-in. Configuration takes effect on the next delivery, without a deploy. Success does not prove the credential works. After sending, check `read_push` and `read_logs`.",
  "owners": [
    "PSH-L0-01",
    "PLD-L0-40"
  ],
  "scenario": "PSH-L0-01"
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["application"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>application | Your account's application `id` from `list_applications`, not its name or label\.<br><br>Type: string |
| /<wbr>properties/<wbr>environment | The environment you address, `production` where absent\.<br><br>Type: string<br>Pattern: ^\(development\|production\)$ |
| /<wbr>properties/<wbr>apns | Apple's provider, or null to remove it; the named secret is proved present at this environment's application scope and moved nowhere\.<br><br>Type: \["object","null"\]<br>Required fields: \["team\_id","key\_id","bundle\_id","key\_secret\_name","environment"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>apns/<wbr>properties/<wbr>team\_id | Ten\-character Apple team id from your Developer membership page\.<br><br>Type: string |
| /<wbr>properties/<wbr>apns/<wbr>properties/<wbr>key\_id | Ten\-character signing\-key id from Apple's Keys page, created with the \.p8 key\.<br><br>Type: string |
| /<wbr>properties/<wbr>apns/<wbr>properties/<wbr>bundle\_id | The app's bundle identifier, the notification's topic\.<br><br>Type: string |
| /<wbr>properties/<wbr>apns/<wbr>properties/<wbr>key\_secret\_name | The custody NAME of the stored \.p8 signing key at this environment scope; never pass a value\.<br><br>Type: string |
| /<wbr>properties/<wbr>apns/<wbr>properties/<wbr>environment | Apple's gateway: `sandbox` for a debug build, `production` for a store build\.<br><br>Type: string<br>Allowed values: \["production","sandbox"\] |
| /<wbr>properties/<wbr>fcm | Google's provider, or null to remove it; the named secret is proved present at this environment's application scope and moved nowhere\.<br><br>Type: \["object","null"\]<br>Required fields: \["project\_id","service\_account\_secret\_name"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>fcm/<wbr>properties/<wbr>project\_id | Firebase project id: six to thirty lowercase letters, digits or hyphens, starting with a letter\.<br><br>Type: string |
| /<wbr>properties/<wbr>fcm/<wbr>properties/<wbr>service\_account\_secret\_name | The custody NAME of the stored service\-account JSON file at this environment scope; never pass a value\.<br><br>Type: string |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","push","detail"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>push | Type: object<br>Required fields: \["application","environment","apns","fcm"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>application | Type: string |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>environment | Type: string<br>Allowed values: \["development","production"\] |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>apns | Type: \["object","null"\]<br>Required fields: \["team\_id","key\_id","bundle\_id","key\_secret\_name","environment"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>apns/<wbr>properties/<wbr>team\_id | The ten\-character Apple team identifier\.<br><br>Type: string |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>apns/<wbr>properties/<wbr>key\_id | The ten\-character identifier of the APNs signing key\.<br><br>Type: string |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>apns/<wbr>properties/<wbr>bundle\_id | The app's bundle identifier, the notification's topic\.<br><br>Type: string |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>apns/<wbr>properties/<wbr>key\_secret\_name | The custody NAME of the stored \.p8 signing key at this environment scope; never a value\.<br><br>Type: string |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>apns/<wbr>properties/<wbr>environment | Which of Apple's two gateways this environment's pushes go to\.<br><br>Type: string<br>Allowed values: \["production","sandbox"\] |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>fcm | Type: \["object","null"\]<br>Required fields: \["project\_id","service\_account\_secret\_name"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>fcm/<wbr>properties/<wbr>project\_id | The Firebase project identifier\.<br><br>Type: string |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>fcm/<wbr>properties/<wbr>service\_account\_secret\_name | The custody NAME of the stored service\-account JSON file at this environment scope; never a value\.<br><br>Type: string |
| /<wbr>properties/<wbr>detail | Type: string |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "required": [
      "application"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$",
        "description": "The environment you address, `production` where absent."
      },
      "apns": {
        "type": [
          "object",
          "null"
        ],
        "description": "Apple's provider, or null to remove it; the named secret is proved present at this environment's application scope and moved nowhere.",
        "required": [
          "team_id",
          "key_id",
          "bundle_id",
          "key_secret_name",
          "environment"
        ],
        "properties": {
          "team_id": {
            "type": "string",
            "description": "Ten-character Apple team id from your Developer membership page."
          },
          "key_id": {
            "type": "string",
            "description": "Ten-character signing-key id from Apple's Keys page, created with the .p8 key."
          },
          "bundle_id": {
            "type": "string",
            "description": "The app's bundle identifier, the notification's topic."
          },
          "key_secret_name": {
            "type": "string",
            "description": "The custody NAME of the stored .p8 signing key at this environment scope; never pass a value."
          },
          "environment": {
            "type": "string",
            "enum": [
              "production",
              "sandbox"
            ],
            "description": "Apple's gateway: `sandbox` for a debug build, `production` for a store build."
          }
        },
        "additionalProperties": false
      },
      "fcm": {
        "type": [
          "object",
          "null"
        ],
        "description": "Google's provider, or null to remove it; the named secret is proved present at this environment's application scope and moved nowhere.",
        "required": [
          "project_id",
          "service_account_secret_name"
        ],
        "properties": {
          "project_id": {
            "type": "string",
            "description": "Firebase project id: six to thirty lowercase letters, digits or hyphens, starting with a letter."
          },
          "service_account_secret_name": {
            "type": "string",
            "description": "The custody NAME of the stored service-account JSON file at this environment scope; never pass a value."
          }
        },
        "additionalProperties": false
      }
    },
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "push",
      "detail"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "push": {
        "type": "object",
        "required": [
          "application",
          "environment",
          "apns",
          "fcm"
        ],
        "properties": {
          "application": {
            "type": "string"
          },
          "environment": {
            "type": "string",
            "enum": [
              "development",
              "production"
            ]
          },
          "apns": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "team_id",
              "key_id",
              "bundle_id",
              "key_secret_name",
              "environment"
            ],
            "properties": {
              "team_id": {
                "type": "string",
                "description": "The ten-character Apple team identifier."
              },
              "key_id": {
                "type": "string",
                "description": "The ten-character identifier of the APNs signing key."
              },
              "bundle_id": {
                "type": "string",
                "description": "The app's bundle identifier, the notification's topic."
              },
              "key_secret_name": {
                "type": "string",
                "description": "The custody NAME of the stored .p8 signing key at this environment scope; never a value."
              },
              "environment": {
                "type": "string",
                "enum": [
                  "production",
                  "sandbox"
                ],
                "description": "Which of Apple's two gateways this environment's pushes go to."
              }
            },
            "additionalProperties": false
          },
          "fcm": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "project_id",
              "service_account_secret_name"
            ],
            "properties": {
              "project_id": {
                "type": "string",
                "description": "The Firebase project identifier."
              },
              "service_account_secret_name": {
                "type": "string",
                "description": "The custody NAME of the stored service-account JSON file at this environment scope; never a value."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "detail": {
        "type": "string"
      }
    },
    "additionalProperties": false
  }
}
```

## Shared contracts

- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
