Space API V2 - Introduction

The Archiogic Space API provides REST (opens new window) access to relevant entities such as floors, spaces and furniture assets.

INFO

You’re browsing the documentation for Space API V2. For V1, click here.
View the change logs to see what has changed.

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:archive Archive floors within your organization.
customFields:readPublic Read custom field on floor, space and asset resources of public floors within your organization.
customFields:readPrivate Read custom field on floor, space and asset resources of private floors within your organization.
customFields:write Write and delete custom field on floor, space and asset resources of both private and public floors within your organization.

Matching Space API V1 scopes to V2

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

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
  • customFields:readPublic

Generate

Generate publishable access tokens for your organization on the access tokens page of the developer portal. There is a 100 publishable access token limit per organization.

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 for your organization on the access tokens page of the developer portal. There is a 100 secret access token limit per organization.

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

Temporary Access Token Grant

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

Temporary Access Token Usage

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 =
  | "customFields"
  | "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 fields reads and creating temporary access tokens.
3000 requests/5 minutes per IP Floor, space and asset resource queries, reading scene structure of a floor, getting 2d floor plan of a floor and archiving/unarchiving floors.
1000 requests/5 minutes per IP Writing and deleting custom fields.