---
openapi: 3.0.3
info:
  title: Braze REST API – Update push credentials
  description: |
    ## Prerequisites

    To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) with the `apps.push_credential` permission.

    ## Rate limit

    We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/).
  version: 1.0.0
  contact:
    name: Braze Support
    url: https://www.braze.com/docs/braze_support/
  license:
    name: Braze Documentation
    url: https://www.braze.com/docs/api/home/
servers:
  - url: https://rest.iad-01.braze.com
    description: US-01
  - url: https://rest.iad-02.braze.com
    description: US-02
  - url: https://rest.iad-03.braze.com
    description: US-03
  - url: https://rest.iad-04.braze.com
    description: US-04
  - url: https://rest.iad-05.braze.com
    description: US-05
  - url: https://rest.iad-06.braze.com
    description: US-06
  - url: https://rest.iad-07.braze.com
    description: US-07
  - url: https://rest.iad-08.braze.com
    description: US-08
  - url: https://rest.us-10.braze.com
    description: US-10
  - url: https://rest.fra-01.braze.eu
    description: EU-01
  - url: https://rest.fra-02.braze.eu
    description: EU-02
  - url: https://rest.au-01.braze.com
    description: AU-01
  - url: https://rest.id-01.braze.com
    description: ID-01
  - url: https://rest.jp-01.braze.com
    description: JP-01
  - url: https://rest.kr-01.braze.com
    description: KR-01
security:
- BearerAuth: []
paths:
  /apps/push_credential/update:
    post:
      summary: Update push credentials
      operationId: post_apps_push_credential_update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePushCredentialRequest'
            examples:
              apple:
                summary: iOS (APNs)
                description: The `apple.certificate` value must be Base64-encoded, and `apple.apns_gateway` must be set to either `prod` or `dev`.
                value:
                  app_id: "{YOUR_APP_IDENTIFIER}"
                  apple:
                    certificate: "{BASE64_ENCODED_STRING}"
                    jwt_key_id: "{YOUR_KEY_ID}"
                    jwt_team_id: "{YOUR_TEAM_ID}"
                    jwt_bundle_id: "{YOUR_BUNDLE_ID}"
                    apns_gateway: prod
              firebase:
                summary: Android (Firebase Cloud Messaging)
                description: The `firebase.credential` value must be Base64-encoded.
                value:
                  app_id: "{YOUR_APP_IDENTIFIER}"
                  firebase:
                    credential: "{BASE64_ENCODED_STRING}"
              huawei:
                summary: Android (Huawei Mobile Services)
                value:
                  app_id: "{YOUR_APP_IDENTIFIER}"
                  huawei:
                    app_id: "{YOUR_HUAWEI_APP_ID}"
                    app_secret: "{YOUR_HUAWEI_APP_SECRET}"
              kindle:
                summary: Kindle (Amazon Device Messaging)
                value:
                  app_id: "{YOUR_APP_IDENTIFIER}"
                  kindle:
                    client_id: "{YOUR_ADM_CLIENT_ID}"
                    client_secret: "{YOUR_ADM_CLIENT_SECRET}"
      responses:
        "201":
          description: |
            The request succeeded and the push credentials were updated. No action needed.

            If the credentials are updated successfully, you'll receive a response with the status code `201`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePushCredentialResponse'
              examples:
                success:
                  summary: Credentials updated
                  value:
                    message: success
        "400":
          description: |
            Bad request. To resolve it:

            - **The `app_id` is missing or empty:** Include a valid `app_id` from the [API Keys page]({{site.baseurl}}/user_guide/administer/global/workspace_settings/apis_and_identifiers/).
            - **The `app_id` isn't a string or doesn't match an app in this workspace:** Pass a valid `app_id` string for an app in this workspace.
            - **The app's platform isn't supported:** Call this endpoint for an iOS (APNs), Android (Firebase or Huawei), or Kindle (ADM) app.
            - **The credential block for the app's platform is missing:** Include the credential block that matches the app's platform.
            - **The platform credential block isn't an object:** Pass the credential block as an object.
            - **A credential value in the block is invalid:** Correct the flagged credential field, then retry. The error message is the specific validation error for the credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_app_id:
                  summary: The app_id is missing or empty
                  value:
                    message: "'app_id' cannot be null or empty"
                invalid_app_id:
                  summary: The app_id isn't valid
                  value:
                    message: "Invalid 'app_id'"
                unsupported_platform:
                  summary: The app's platform isn't supported
                  value:
                    message: Only iOS (APNs), Android (Firebase, Huawei), and Kindle (ADM) apps are supported
                missing_apple:
                  summary: The apple block is missing for an iOS app
                  value:
                    message: "'apple' field must be provided for an iOS app"
                missing_firebase:
                  summary: The firebase block is missing for an Android app
                  value:
                    message: "'firebase' field must be provided for an Android app"
                missing_huawei:
                  summary: The huawei block is missing for a Huawei app
                  value:
                    message: "'huawei' field must be provided for a Huawei app"
                missing_kindle:
                  summary: The kindle block is missing for a Kindle app
                  value:
                    message: "'kindle' field must be provided for a Kindle app"
                apple_not_object:
                  summary: The apple block isn't an object
                  value:
                    message: "'apple' field must be an object"
                firebase_not_object:
                  summary: The firebase block isn't an object
                  value:
                    message: "'firebase' field must be an object"
                huawei_not_object:
                  summary: The huawei block isn't an object
                  value:
                    message: "'huawei' field must be an object"
                kindle_not_object:
                  summary: The kindle block isn't an object
                  value:
                    message: "'kindle' field must be an object"
                invalid_apns_gateway:
                  summary: A credential value is invalid (example)
                  value:
                    message: "'apple.apns_gateway' must be one of: dev, prod"
        "401":
          description: |
            Unauthorized. The REST API key is missing, malformed, or sent to the wrong REST endpoint. Send the key as `Authorization: Bearer YOUR_REST_API_KEY` to the correct [REST endpoint]({{site.baseurl}}/api/basics/#endpoints). For more causes, see [Errors and responses]({{site.baseurl}}/api/errors/#fatal-errors).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_api_key:
                  summary: Invalid API key
                  value:
                    message: 'Invalid API key: YOUR_REST_API_KEY'
        "403":
          description: Access denied. The API key lacks the required permission. Use a key with the `apps.push_credential` permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                access_denied:
                  summary: Access denied
                  value:
                    message: Access Denied
        "429":
          description: |
            Rate limited. You exceeded the rate limit for this endpoint. Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                over_rate_limit:
                  summary: Over rate limit
                  value:
                    message: You have exceeded your limit of 250000 requests per hour. Please contact your account executive to increase your limit. If you do not have their info, you may contact Braze directly at https://www.braze.com/contact/.
        5XX:
          description: |
            Internal server error. An unexpected error occurred on the Braze server. Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: REST API key
      description: |
        REST API keys are created in the Braze dashboard at **Settings → APIs and
        Identifiers → API Keys**. The key must include the `apps.push_credential` permission.
        Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`.
  schemas:
    AppleCredentials:
      title: iOS (APNs) credentials
      type: object
      required: [certificate, jwt_key_id, jwt_team_id, jwt_bundle_id, apns_gateway]
      properties:
        certificate:
          type: string
          description: The Base64-encoded `.p8` authentication key. Only `.p8` authentication keys are supported; `.p12` and `.pem` certificates aren't supported by this endpoint.
          example: "{BASE64_ENCODED_STRING}"
        jwt_key_id:
          type: string
          description: The key ID for the `.p8` authentication key.
          example: "{YOUR_KEY_ID}"
        jwt_team_id:
          type: string
          description: Your Apple Developer team ID.
          example: "{YOUR_TEAM_ID}"
        jwt_bundle_id:
          type: string
          description: Your app's bundle ID.
          example: "{YOUR_BUNDLE_ID}"
        apns_gateway:
          type: string
          enum: [prod, dev]
          description: The APNs environment. Available values are `prod` and `dev`.
          example: prod
    FirebaseCredentials:
      title: Android (Firebase Cloud Messaging) credentials
      type: object
      required: [credential]
      properties:
        credential:
          type: string
          description: The Base64-encoded Firebase service account JSON.
          example: "{BASE64_ENCODED_STRING}"
    HuaweiCredentials:
      title: Android (Huawei Mobile Services) credentials
      type: object
      required: [app_id, app_secret]
      properties:
        app_id:
          type: string
          description: Your Huawei app ID.
          example: "{YOUR_HUAWEI_APP_ID}"
        app_secret:
          type: string
          description: Your Huawei app secret.
          example: "{YOUR_HUAWEI_APP_SECRET}"
    KindleCredentials:
      title: Kindle (Amazon Device Messaging) credentials
      type: object
      required: [client_id, client_secret]
      properties:
        client_id:
          type: string
          description: Your Amazon Device Messaging client ID.
          example: "{YOUR_ADM_CLIENT_ID}"
        client_secret:
          type: string
          description: Your Amazon Device Messaging client secret.
          example: "{YOUR_ADM_CLIENT_SECRET}"
    UpdatePushCredentialRequest:
      title: Update push credentials request
      type: object
      required: [app_id]
      description: |
        Include one platform object per request: `apple`, `firebase`, `huawei`, or `kindle`.

        \* Include exactly one platform object per request.
      properties:
        app_id:
          type: string
          description: The app identifier API key for the app you want to update. Find it in the dashboard under **Settings** > **App Settings**, next to the **API Key** field. For more information, see [App identifier]({{site.baseurl}}/api/identifier_types#app-identifier).
          example: "{YOUR_APP_IDENTIFIER}"
        apple:
          allOf:
            - $ref: '#/components/schemas/AppleCredentials'
          description: Required\*. The iOS (APNs) credentials.
        firebase:
          allOf:
            - $ref: '#/components/schemas/FirebaseCredentials'
          description: Required\*. The Android (Firebase Cloud Messaging) credentials.
        huawei:
          allOf:
            - $ref: '#/components/schemas/HuaweiCredentials'
          description: Required\*. The Android (Huawei Mobile Services) credentials.
        kindle:
          allOf:
            - $ref: '#/components/schemas/KindleCredentials'
          description: Required\*. The Kindle (Amazon Device Messaging) credentials.
    UpdatePushCredentialResponse:
      title: Update push credentials response
      type: object
      properties:
        message:
          type: string
          example: success
    ErrorResponse:
      title: Error
      type: object
      properties:
        message:
          type: string
          description: The error message describing why the request failed.
        errors:
          type: array
          description: Non-fatal errors encountered while processing the request. Data unaffected by these errors is still processed.
          items:
            type: object
            properties:
              type:
                type: string
                description: The error type.
