Skip to content
API Cloud

Guidance for using Audience Enforcement:

###What is the purpose of Audience Enforcement?

The audience claim in a JWT token is used by APICloud to verify that the token is being only presented to the intended recipients.

###What Will Be Enforced in the Audience Claim?

All the newly created API deployments created after below timelines will be enforced with audience enforcement.

  • Development & QA: April 7th, 4:30 PM UTC
  • Staging: April 8th, 10:30 AM UTC
  • Production: April 9th, 10:30 AM UTC

###Consuming Newly Created API Deployments

To successfully consume newly deployed APIs, the consuming application must pass the appropriate scope during token generation. This scope is tied to the specific proxy you are consuming. An attempt to call an API with an access token that does not contain the target API’s scope will result in a 403 error.

####Locating the API Application Scope The required scope can be found in the Products (Consumer) section of the Trimble Cloud Console. Follow the steps below: #####During New Subscription Workflow:

  1. Log in to Trimble Cloud Console and navigate to the ‘Products’ section.
  2. Search for and select the Product you wish to consume.
  3. On the Product Summary page, choose the appropriate version and type.
  4. Scroll down to the bottom of the page to locate the available API Application scopes.
  5. Copy the scope value including the prefix and suffix (if no suffix is present, copy the available scope value).
  6. Click ‘Subscribe’ to subscribe the product to your application.
  7. Use the copied scope during token generation as shown below.

#####During Existing Subscription Workflow:

  1. Navigate to the ‘Products’ section in Trimble Cloud Console.
  2. Search for and select the Product already being consumed.
  3. In the Product Summary page, select the appropriate version and type.
  4. Scroll down to view the API Application scopes.
  5. Copy the full scope (including prefix and suffix, if available).
  6. Use the copied scope when generating the token to continue consuming the API.

###Token Generation (Sample Curl Commands) ####Production:

Terminal window
curl --location 'https://id.trimble.com/oauth/token' \
--header 'Authorization: Basic <prodApplicationBase64>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=<scopeName>'

####Staging:

Terminal window
curl --location 'https://stage.id.trimblecloud.com/oauth/token' \
--header 'Authorization: Basic <stageApplicationBase64>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=<scopeName>'

####Understanding Scope Prefix and Suffix In a scope string, the prefix typically represents the API service name, while the suffix defines the specific permission. These parts are separated by a colon (:). #####Example:

######File-Service-Demo:file.read

  • Prefix: File-Service-Demo
  • Suffix: file.read

For Scopes without any prefix & suffix the display will be as below,