Authentication

3. Get API access

ArchWalk 360 must be enabled for the Organization. After that, either of these onboarding paths produces the same Integration, credential, and Partner API:

Managed onboarding. ArchWalk can provision an Integration and issue the initial credential for you (media policy, allowed origins, and key handoff included). The customer does not have to log into the ArchWalk portal. There is no impersonation of Organization users.

Self-serve onboarding. An entitled Organization admin can configure the same Integration through ArchWalk settings (media policy, allowed origins, and credentials).

An Integration may be created before any Experiences. If your customer has already configured and published a Standalone Experience in ArchWalk, they can open the Organization's /archwalk-360 library and choose Connect to integration. They select your Integration and enter the exact external_resource_id your platform sends (and optional external_customer_id when your contract uses customer scoping). This binds the existing Experience, including its Panoramas, draft, live publication, and stable public_id; it does not clone content. Your next POST /api/v1/360/experiences with that exact Integration and identity returns 200 and the same experience_id. A different Integration key remains unable to read it. Choose a media policy compatible with existing Panoramas; an external-only Integration cannot bind existing managed views.

In both cases:

1. The raw API key is shown once. Store it in your secret manager immediately.
2. The existing raw key cannot be retrieved later. Rotate to obtain a replacement secret.
3. Create, rotate, and revoke are onboarding/settings operations, not /api/v1/360 Partner API routes. The Partner API only uses the key.
4. /api/v1/360 behavior is identical regardless of who provisioned the Integration.

Authorization header (actual format)

Authorization: Bearer <your-api-key>

The key is a Bearer token. There is no X-API-Key header.

Token shape:

aw360_sk_<credential-api-id>.<secret>

Example placeholder only:

export AW360_API_KEY="aw360_sk_<credential-id>.<secret>"

Missing, malformed, unknown, wrong-secret, revoked, and expired credentials all return the same generic 401. That is intentional: the API does not reveal which part of the token failed.

401 credential responses include:

WWW-Authenticate: Bearer realm="archwalk-360"

Successful 2xx responses do not send that challenge header.

4. Scopes

Closed vocabulary (credentials and Creator permitted_actions use the same strings):

Scopes are not implied. experiences:write does not grant publish or upload.

creator_sessions:issue may appear on an API credential. It must not appear on a Creator session's permitted_actions.

Recommended minimal sets

Viewer / API publishing with managed uploads

experiences:read, experiences:write, experiences:publish, panoramas:read, panoramas:write, panoramas:upload

Viewer / API publishing with external media only

experiences:read, experiences:write, experiences:publish, panoramas:read, panoramas:write

Embedded Creator

Credential: creator_sessions:issue plus every action the editor must perform (typically read/write/publish/upload as above). Session permitted_actions must be a subset of the issuing credential's scopes.

Use least privilege. A Viewer-only backend does not need creator_sessions:issue.

5. Rotate and revoke keys

After rotation, switch your servers to the new AW360_API_KEY immediately. The old key stops working for /api/v1/360.

Create, rotate, and revoke are performed during managed handoff or by an Organization admin in ArchWalk settings — never via /api/v1/360.

6. API key vs Creator session

The API key must never be sent to a browser. The Creator token must never be placed in the iframe src, query string, or hash.

7. External identity

Map your listing id onto an Experience without storing ArchWalk numeric IDs.

Fields (actual schema — there is no resource-type field):

Uniqueness is per Integration: the pair (external_customer_id, external_resource_id) is unique inside that Integration. The same room_12345 on another Integration is a different Experience.

Example (AcmeStay):

{
  "name": "Ocean Suite",
  "external_resource_id": "room_12345",
  "external_customer_id": "property_88"
}

POST /api/v1/360/experiences is create-or-resolve:

• First call → 201 and a new Experience.
• Same identity again → 200 and the existing Experience (safe retry).
• If that identity is pending deletion → 409 conflict (the id remains reserved).

The browser must not choose another tenant's resource identity. Only your authenticated backend should call create/resolve.

For imported hotel inventory, external_resource_id is usually a visual variant id (for example room_type_deluxe_king), not a physical room number. Optional external_customer_id namespaces that id by customer or resort when your platform already does. See 29. Partner plugin integration.