API Authorization
There are two groups of calls to the Geometry Backend API, which use different methods of authorization. Please refer to the Swagger API documentation for a complete list of API calls.
Calls based on a session id
The concept of sessions is used to provide a basic level of protection for your models when embedding them from web browsers (typically using our viewer). Sessions are also used for the purpose of billing API usage and have a limited lifetime.
Note: When viewing the Swagger documentation, watch out for {sessionId} to identify calls based on a session id.
A typical use case for embedding a ShapeDiver model in a browser is a publicly available product configurator. The viewer needs to access the metadata of the models (What are the parameters? Which outputs and exports exist for the model?), and it needs to trigger computation requests and download the resulting output data. This implies that the related API calls need to be accessible to anyone accessing your product configurator. On the other hand, your competitors should not be able to embed your models. This is achieved by checking the origin of requests to the Geometry Backend against the whitelisted domains for your model.
A new session is created by sending a session init call including a ticket for your model to the Geometry Backend. The viewer does this whenever loading a ShapeDiver model, e.g. whenever you open or reload a web page that embeds a model. Read more about how the viewer represents sessions here.
The ticket is an API key for your model and is required for creating new sessions. Please use the Platform to obtain a ticket depending on the type of your application:
Ticket for embedding: Use this type of ticket in case your application runs in a web browser.
Ticket for backend access: Use this type of ticket for applications that do not run in a web browser.
Note: It is possible to request tickets programmatically by using the Platform Backend API.
Examples
JWT authorization for sessions
While session-based authorization is sufficient for many web applications like e-commerce configurators, the Geometry Backend allows configuring your models to require a stronger authorization mechanism for creating and accessing sessions, using a ticket and a JWT. The corresponding model setting on the Platform Backend API is called require_token. This can be enabled per model or globally for all models of your user or organization account (setting force_require_token). Once this is enabled, your models can not be embedded anymore without providing a ticket and a JWT to the viewer.
Note: The Platform Backend API offers functionality for programmatically obtaining both JWT and ticket for your model.
Calls based on a model id
These calls identify a model based on its unique id. They must be authorized by a JWT which can be obtained using the Platform Backend API. Depending on the scope of the JWT, specific permissions are granted or not.
These calls are used to manage models. For example, the Platform Backend issues a create model call to the user’s Geometry Backend system when uploading a new model, and it uses an update model call when you save a model on the Edit screen.
Note: When viewing the Swagger documentation, watch out for {modelId} to identify these calls.
Some of the permissions are available to the Platform Backend only, and are never provided as part of the JWTs which you can obtain using the Platform Backend API. As an example, this is the case for the permissions required to update embedding settings for your models, and other settings related to enforcement of product features. You can make use of the Platform Backend API to programmatically update those settings within the limits of your subscription.