Identity Cloud

Upload an iOS apple-app-site-association file

Overview

To help you integrate your iOS apps with Identity Cloud, you can upload an apple-app-site-association file to your Identity Cloud environment. The apple-app-site-association file creates a secure association between your domain and your app. This allows you to use universal links to open your app from your website.

To upload the file, use the /.well-known/apple-app-site-association endpoint. Access the endpoint by using your custom domain.

Make sure that you have already set up a custom domain for each environment and realm where you need to upload an iOS apple-app-site-association file.

Upload or replace an apple-app-site-association file

  1. Get an access token for the realm using the custom domain. Refer to Get an access token.

  2. Upload or replace the apple-app-site-association file by making a PUT request:

    Show request
    $ curl \
    --request PUT 'https://<custom-domain-fqdn>/.well-known/apple-app-site-association' \(1)
    --header 'Authorization: Bearer <access-token>' \(2)
    --header 'Content-Type: application/json' \
    --data-raw '{(3)
      "applinks": {
        "details": [
          {
            "appIDs": [
              "XXXXXXXXXX.com.example.AppName"
            ],
            "components": [
              {
                "/": "/reset/*",
                "comment": "Success after reset password journey"
              }
            ]
          }
        ]
      },
      "webcredentials": {
        "apps": [
          "XXXXXXXXXX.com.example.AppName"
        ]
      }
    }'
    1 Replace <custom-domain-fqdn> with your custom domain; for example, id.mycompany.com.
    2 Replace <access-token> with your access token.
    3 Replace the example apple-app-site-association JSON content with your own JSON content.
    Show response
    {
      "applinks": {
        "details": [
          {
            "appIDs": [
              "XXXXXXXXXX.com.example.AppName"
            ],
            "components": [
              {
                "/": "/reset/*",
                "comment": "Success after reset password journey"
              }
            ]
          }
        ]
      },
      "webcredentials": {
        "apps": [
          "XXXXXXXXXX.com.example.AppName"
        ]
      }
    }

    For more information on creating and using a apple-app-site-association file, refer to Supporting associated domains.

Verify an apple-app-site-association file

You do not need an access token to view the publicly accessible apple-app-site-association file.
  1. View the apple-app-site-association file using a GET request:

    Show request
    $ curl \
    --request GET 'https://<custom-domain-fqdn>/.well-known/apple-app-site-association'(1)
    1 Replace <custom-domain-fqdn> with your custom domain; for example, id.mycompany.com.
    Show response
    {
      "applinks": {
        "details": [
          {
            "appIDs": [
              "XXXXXXXXXX.com.example.AppName"
            ],
            "components": [
              {
                "/": "/reset/*",
                "comment": "Success after reset password journey"
              }
            ]
          }
        ]
      },
      "webcredentials": {
        "apps": [
          "XXXXXXXXXX.com.example.AppName"
        ]
      }
    }

Delete an apple-app-site-association file

  1. Get an access token for the realm that is using the custom domain. Refer to Get an access token.

  2. Remove the apple-app-site-association file by making a DELETE request:

    Show request
    curl \
    --request DELETE 'https://<custom-domain-fqdn>/.well-known/apple-app-site-association'\(1)
    --header 'Authorization: Bearer <access-token>'(2)
    1 Replace <custom-domain-fqdn> with your custom domain; for example, id.mycompany.com.
    2 Replace <access-token> with the access token.
    Show response
    {
      "applinks": {
        "details": [
          {
            "appIDs": [
              "XXXXXXXXXX.com.example.AppName"
            ],
            "components": [
              {
                "/": "/reset/*",
                "comment": "Success after reset password journey"
              }
            ]
          }
        ]
      },
      "webcredentials": {
        "apps": [
          "XXXXXXXXXX.com.example.AppName"
        ]
      }
    }
Copyright © 2010-2022 ForgeRock, all rights reserved.