Documentation

AASA

Configure Apple App Site Association, Universal Links, App Clips, Passkeys, and Handoff via the OrbitKit API.

The Apple App Site Association (AASA) configuration controls Universal Links, App Clips, Passkeys, and Handoff for your app. OrbitKit generates the apple-app-site-association JSON file and serves it at the correct .well-known path.

See Apple’s documentation on Supporting associated domains and the apple-app-site-association file format.

Endpoints

Method Path Description
GET /api/apps/:appId/aasa Get AASA configuration
PUT /api/apps/:appId/aasa Save AASA configuration

Get AASA configuration

GET /api/apps/:appId/aasa

Response

{
  "universalLinks": {
    "appIDs": ["A1B2C3D4E5.com.example.weatherapp"],
    "paths": [
      {
        "pattern": "/products/*",
        "exclude": false,
        "comment": "Product pages"
      },
      {
        "pattern": "/admin/*",
        "exclude": true,
        "comment": "Exclude admin routes"
      }
    ]
  },
  "appClips": {
    "appIDs": ["A1B2C3D4E5.com.example.weatherapp.Clip"]
  },
  "webCredentials": {
    "appIDs": ["A1B2C3D4E5.com.example.weatherapp"]
  },
  "activityContinuation": {
    "appIDs": ["A1B2C3D4E5.com.example.weatherapp"]
  },
  "updatedAt": 1712345678000
}

Returns 404 NOT_FOUND if no AASA configuration exists.

Save AASA configuration

PUT /api/apps/:appId/aasa

Saves the AASA configuration. The API validates:

  • App ID format — must be TEAMID.bundleid (e.g., A1B2C3D4E5.com.example.app)
  • Path patterns — must start with /

Set any section to null to disable it.

Request body

Field Type Required Description
universalLinks object or null No Universal Links config
universalLinks.appIDs string[] Yes (if section present) 1–10 App IDs
universalLinks.paths array No URL path patterns (max 50)
universalLinks.paths[].pattern string Yes Path pattern (e.g., /products/*)
universalLinks.paths[].exclude boolean No Exclude this pattern (default: false)
universalLinks.paths[].comment string No Description (max 200)
appClips object or null No App Clips config
appClips.appIDs string[] Yes (if section present) 1–5 App Clip IDs
webCredentials object or null No Passkeys config
webCredentials.appIDs string[] Yes (if section present) 1–10 App IDs
activityContinuation object or null No Handoff config
activityContinuation.appIDs string[] Yes (if section present) 1–10 App IDs

Full example

curl -X PUT https://api.orbitkit.io/api/apps/-NtestApp123/aasa \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "universalLinks": {
      "appIDs": ["A1B2C3D4E5.com.example.weatherapp"],
      "paths": [
        {"pattern": "/products/*", "exclude": false, "comment": "Product pages"}
      ]
    },
    "webCredentials": {
      "appIDs": ["A1B2C3D4E5.com.example.weatherapp"]
    },
    "appClips": null,
    "activityContinuation": null
  }'

struct AASAConfig: Codable {
    var universalLinks: UniversalLinks?
    var appClips: AppClips?
    var webCredentials: WebCredentials?
    var activityContinuation: ActivityContinuation?

    struct UniversalLinks: Codable {
        let appIDs: [String]
        var paths: [PathRule]?
        struct PathRule: Codable {
            let pattern: String
            var exclude: Bool = false
            var comment: String?
        }
    }
    struct AppClips: Codable { let appIDs: [String] }
    struct WebCredentials: Codable { let appIDs: [String] }
    struct ActivityContinuation: Codable { let appIDs: [String] }
}

let config = AASAConfig(
    universalLinks: .init(
        appIDs: ["A1B2C3D4E5.com.example.weatherapp"],
        paths: [.init(pattern: "/products/*", comment: "Product pages")]
    ),
    webCredentials: .init(appIDs: ["A1B2C3D4E5.com.example.weatherapp"])
)

var request = URLRequest(url: URL(string: "https://api.orbitkit.io/api/apps/\(appId)/aasa")!)
request.httpMethod = "PUT"
request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONEncoder().encode(config)

const res = await fetch(`https://api.orbitkit.io/api/apps/${appId}/aasa`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    universalLinks: {
      appIDs: ["A1B2C3D4E5.com.example.weatherapp"],
      paths: [{ pattern: "/products/*", exclude: false, comment: "Product pages" }],
    },
    webCredentials: { appIDs: ["A1B2C3D4E5.com.example.weatherapp"] },
    appClips: null,
    activityContinuation: null,
  }),
});
const saved = await res.json();

Response

Returns the saved AASA configuration object (same shape as GET response).

Errors

Code Status When
VALIDATION_FAILED 400 Invalid App ID format or path pattern