Authentication

Learn how to authenticate requests to Substance 3D APIs.

Overview

Every request made to Substance 3D APIs must include an encrypted access token.

Your secure, server-side application retrieves an access token by making a request to the Adobe Identity Management System (IMS) with your Client ID and Client Secret.

Prerequisites

This tutorial assumes you have worked with your Adobe Representative and have the following:

An Adobe Developer Console account.
A project with Substance 3D API OAuth Server-to-Server credentials set up.
Access to your Client ID and Client Secret from the Adobe Developer Console project. Securely store these credentials and never expose them in client-side or public code.

Retrieve an access token

A temporary access token validates calls to the API. This token can be generated directly in the Developer Console, or it can be generated programmatically by following the steps below.

First, open a secure terminal and export your Client ID and Client Secret as environment variables so that later commands can access them:

export S3D_FF_SERVICES_CLIENT_ID=<Your_Client_ID>
export S3D_FF_SERVICES_CLIENT_SECRET=<Your_Client_Secret>
Copied to your clipboard
export S3D_FF_SERVICES_CLIENT_ID=<Your_Client_ID>
export S3D_FF_SERVICES_CLIENT_SECRET=<Your_Client_Secret>

Next, run the following command to generate an access token:

curl --location 'https://ims-na1.adobelogin.com/ims/token/v3' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode "client_id=$S3D_FF_SERVICES_CLIENT_ID" \
--data-urlencode "client_secret=$S3D_FF_SERVICES_CLIENT_SECRET" \
--data-urlencode 'scope=openid,AdobeID,read_organizations,email,firefly_api,firefly_enterprise,profile,substance3d_api.spaces.create,substance3d_api.jobs.create'
Copied to your clipboard
curl --location 'https://ims-na1.adobelogin.com/ims/token/v3' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode "client_id=$S3D_FF_SERVICES_CLIENT_ID" \
--data-urlencode "client_secret=$S3D_FF_SERVICES_CLIENT_SECRET" \
--data-urlencode 'scope=openid,AdobeID,read_organizations,email,firefly_api,firefly_enterprise,profile,substance3d_api.spaces.create,substance3d_api.jobs.create'

The response will look like this:

{
    "access_token": "exampleAccessTokenAsdf123",
    "token_type": "bearer",
    "expires_in": 86399
}
Copied to your clipboard
{
    "access_token": "exampleAccessTokenAsdf123",
    "token_type": "bearer",
    "expires_in": 86399
}

The response includes an expires_in field with the length of time, in seconds, that the access token is valid. Each access token is valid for 24 hours, then your secure server-side application will need to request a new token. The best practice is to securely store the token and refresh it before it expires.

Export your access token as an environment variable:

export S3D_FF_SERVICES_ACCESS_TOKEN=<Your_Access_Token>
Copied to your clipboard
export S3D_FF_SERVICES_ACCESS_TOKEN=<Your_Access_Token>

Execute a test API request

Let's make a test call to a Substance 3D API with the access token.

Make a test call to the Render Model API:

curl --location 'https://s3d.adobe.io/v1/scenes/render-basic' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $S3D_FF_SERVICES_ACCESS_TOKEN" \
--data '{
    "scene": {
      "modelFile": "DamagedHelmet.glb"
    },
    "sources": [
    {
      "url": {
        "url": "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/DamagedHelmet/glTF-Binary/DamagedHelmet.glb"
      }
    }
  ]
}'
Copied to your clipboard
curl --location 'https://s3d.adobe.io/v1/scenes/render-basic' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $S3D_FF_SERVICES_ACCESS_TOKEN" \
--data '{
    "scene": {
      "modelFile": "DamagedHelmet.glb"
    },
    "sources": [
    {
      "url": {
        "url": "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/DamagedHelmet/glTF-Binary/DamagedHelmet.glb"
      }
    }
  ]
}'

A successful response will look something like this:

{
    "$schema": "https://s3d.adobe.io/schemas/RenderModelResponse.json",
    "url": "{JOB_URL}",
    "id": "{JOB_ID}",
    "status": "running"
}
Copied to your clipboard
{
    "$schema": "https://s3d.adobe.io/schemas/RenderModelResponse.json",
    "url": "{JOB_URL}",
    "id": "{JOB_ID}",
    "status": "running"
}