Space API V2 - Introduction

The Archilogic Space API provides REST access to relevant entities such as floors, spaces and furniture assets.

For a detailed overview visit the OpenAPI based endpoint reference.
Layout endpoints are only available to customers using Space Graph.

For complex querying refer to the GraphQL API

Base URL

{METHOD}

https://api.archilogic.com/{version}/{resource}

Authentication and Authorization

All requests to Space API V2 must contain an access token that authenticates your organization and authorizes actions based on the scopes present in the access token.

Space API V2 supports the following new access token types:

1. Publishable access tokens
2. Secret access tokens
3. Temporary access tokens

V2 access tokens can be generated on this page. V2 access tokens cannot be edited.

Scopes

Space API V2 supports the following scopes:

Scope	Description
floor:readPublic	Read public floor, space and asset resources, and the scene structure and floor plan image of public floors within your organization.
floor:readPrivate	Read private floor, space and asset resources, and the scene structure and floor plan image of public floors within your organization.
floor:queryPublic	List and read floor, space and asset resources of public floors within your organization.
floor:queryPrivate	List and read floor, space and asset resources of private floors within your organization.
floor:export	Export floor within your organization.
floor:archive	Archive floors within your organization.
customAttributes:read	Read custom attributes of product, floor, space or asset resources within your organization.
customAttributes:write	Create/Update/Delete custom attributes of product, floor, space or asset resources within your organization.
customAttributeValues:readPublic	Read custom attributes values of product, floor, space or asset resources of public floors within your organization.
customAttributeValues:readPrivate	Read custom attributes values of product, floor, space or asset resources of private floors within your organization.
customAttributeValues:write	Create/Update/Delete custom attributes values of product, floor, space or asset resources within your organization.

Matching Space API V1 scopes to V2

• floor:read = floor:readPrivate + floor:readPublic
• floor:query = floor:queryPrivate + floor:queryPublic

Publishable Access Token

INFO

Publishable tokens for the 3D Embed API should allow the viewer.archilogic.com domain.

Publishable access tokens are used for hosting control of public resources. Hosting control is the problem of deciding which domains can display which floors to visitors. Hosting control is not access control in the sense that it does not prevent access to resources, since it partially relies on the Origin header to make authorization decisions which can be trivially spoofed. Hosting control just restricts sharing links that display floors.

Publishable access tokens enable simple front end only Space API integrations in web browsers if only access to public resources is needed.

Publishable access tokens can be safely published in front end code and can be committed into repositories.

Scopes

Publishable access tokens support only the following scopes:

• floor:readPublic
• floor:queryPublic
• customAttributes:read
• customAttributeValues:readPublic

Generate

Generate publishable access tokens on the access tokens page of the dashboard. There is a 100 publishable access token limit per Archilogic organization account.

Usage

Publishable access tokens should be supplied in the pubtoken query parameter, eg.:

# You need to supply a domain allowed for this token as origin to simualate a browser environment
curl -H "Origin: ${ORIGIN}" \
  "https://api.archilogic.com/v2/floor/${FLOOR_ID}?pubtoken=${PUBLISHABLE_TOKEN}"

Secret Access Token

Secret access tokens are used for access control to private and public resources. Secret access tokens allow performing all actions provided by the Space API and support all scopes.

Secret access tokens should be only used in back end Space API integrations and should be treated with the same care as other back end secrets (like a database password).

Generate

Generate secret access tokens on the access tokens page of the dashboard. There is a 100 secret access token limit per Archilogic organization account.

Usage

Secret access tokens should be supplied in the Authorization header with the AL-Secret-Token authentication type. Example API call:

curl -H "Authorization: AL-Secret-Token ${SECRET_TOKEN}" \
  "https://api.archilogic.com/v2/floor/${FLOOR_ID}"

Temporary Access Token

Secret access token holders can request temporary access tokens from the Space API that they can then pass on to clients to perform the same actions for a limited time that the secret access token authorizes, but without exposing the secret. This simplifies Space API integrations that need access to private resources, as they only have to implement the temporary access token grant on their back end and then make Space API requests directly from the front end with the temporary access token. It is up to the integration to determine the criteria for sharing the temporary tokens (ie. share with authenticated users, share with authenticated users with special privileges, or share with unauthenticated users).

Temporary Access Token Flow

1. Request temporary access token with secret access token for front end

2. Use temporary access token from front end to call Space API V2 directly

Generate

Generate temporary access tokens via the Space API V2 with secret access token authorization. There is no limit on the number of temporary access tokens generated (rate limiting applies).

Method:

POST

https://api.archilogic.com/v2/temporary-access-token/create

Parameters:

JSON object in the body of the request with the following properties:

• scopes {ScopeDefiniton[]}Array of authorization scope definitions (see below for type definition) for the token. The scopes requested must be included in the secret access token's scopes.

type ResourceScope = 'floor'

type ActionScope =
  | 'archive'
  | 'queryPublic'
  | 'queryPrivate'
  | 'readPrivate'
  | 'readPublic'
  | 'write'

interface ScopeDefinition {
  resource: ResourceScope
  action: ActionScope
}

• durationSeconds {number}The validity of the token from its creation in seconds. Minimum 15 minutes, maximum 1 day. Optional, defaults to 1 hour.

Returns:

JSON with the following properties:

• authorization {string} The authorization header value containing the authentication type and the temporary access token.
• expiresAt {number} The time the token expires as Unix time (seconds since epoch in UTC).

Example API call:

curl -X POST \
  -H "Authorization: AL-Secret-Token ${SECRET_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"scopes": [{"resource": "floor", "action": "readPrivate"}], "durationSeconds": 3600}' \
  "https://api.archilogic.com/v2/temporary-access-token/create"

Example response:

{
  "authorization": "AL-Temp-Token XlqHBdUIOF46ah...",
  "expiresAt": 1616079083
}

Usage

Temporary access tokens should be supplied in the Authorization header with the AL-Temp-Token authentication type. Example API call:

curl -H "Authorization: AL-Temp-Token ${TEMPORARY_TOKEN}" \
  "https://api.archilogic.com/v2/floor/${FLOOR_ID}"

Example App

Access Private Models with the Floor plan engine and Temporary Access Tokens

Rate Limiting

The following rate limits apply to requests to Space API V2:

Limit	API calls
30000 requests/5 minutes per IP	Floor, space and asset resource reads, custom attribute reads and creating temporary access tokens.
3000 requests/5 minutes per IP	Floor, space and asset resource queries, reading dxf of a floor, getting 2d floor plan of a floor and archiving/unarchiving floors.
1000 requests/5 minutes per IP	Writing and deleting custom attribute values.