Skip to content
API Cloud

Manage API Scopes

API Providers can configure the OAuth scopes for their APIs. OAuth scopes acts as permissions allowing users to control exactly what data or functionality a third-party application can access on their behalf.

Adding New Scopes

The Cloud Console interface allows API providers to define and configure both static and dynamic OAuth scopes for their API. Properly configured scopes are crucial for managing access permissions for client applications and ensuring user privacy.

To configure scopes for an application, follow these steps:

Sign in to the Pre-production or Production Trimble Cloud Console.

  1. From the left menu in the Trimble Cloud Console, click on the Apis menu item.

  2. Select Apis: The Apis page lists API Applications. From this list, click on the specific API Application that is represented by the following icon to proceed with scope configuration:

    Application Icon

  3. Access Scopes Tab: Within the selected application’s details page, navigate to and click on the Scopes tab. This will display the interface for adding and managing scopes.

    Application Icon

Understanding Scope Types: Static vs. Dynamic

Before adding a new scope, it’s important to understand the two types of scopes supported:

  • Static Scopes: These are pre-defined permissions that grant access to a general resource or action. They do not vary based on a specific instance of a resource.

    • Format: <resource_name>.<action>
    • Example: users.read, files.delete
    • Use Case: Ideal for common, broad permissions that apply to a collection of resources or a general capability.

  • Dynamic Scopes: These scopes allow for more granular permissions that are tied to a specific instance of a resource. This enables granular and highly precise access control, for example, granting access to only a particular document or a specific user’s settings.

    • Format: <resource_name>.<action>:<id>#<human_readable_name>
    • Example: files.read:file_id#file_name, settings.manage:user_profile_id#profile_name
    • Use Case: Ideal for scenarios where an application needs access to a specific item or instance, rather than all items of that type. The #<human_readable_name> part is crucial for presenting a clear and understandable message to the user during the consent process.

Add New Scope Interface Fields

The Add New Scope form presents the following fields for configuration:

Scopes Creation

1. Scope Name (Required)

  • Purpose: This field defines the unique identifier for your OAuth scope. This is the string that client applications will request in their authorization requests.
  • Prefix: Note the pre-filled prefix file-service-api: in this example. This prefix is derived from the “Scope Prefix” field configured when the FileService API Proxy was initially created. All custom scopes created through this interface will be prepended with the resource name string. This helps to prevent naming collisions and clearly identifies scopes belonging to your API resources.
  • Input Format:
    • For Static Scopes: Follow the format <resource_name>.<action>
      • Example Input: files.read
      • Resulting Scope: file-service-api:files.read
    • For Dynamic Scopes: Follow the format <resource_name>.<action>:<id>#<human_readable_name>
      • Example Input: files.read:file_id#file_name
      • Resulting Scope: file-service-api:files.read:file_id#file_name
  • Validation:
    • The resource_name should be descriptive of the resource (e.g., users, products, files).
    • The action should describe the operation (e.g., read, write, delete, manage).
    • For dynamic scopes, ensure the <id> is a valid identifier for the resource instance and the <human_readable_name> is concise and user-friendly.

  • Purpose: This is the message that will be displayed to the end-user on the consent screen when a client application requests this particular scope. It should clearly and concisely explain what permission the application is asking for.

  • Input Guidance:

    • Keep it Short: Users quickly scan consent screens. A brief message is more effective.
    • Be Clear and Understandable: Avoid technical jargon. Use plain language that a non-technical user can comprehend.
    • Focus on the User’s Data/Actions: Explain what the application will do or can access with this permission.
    • Examples:
      • For file-service-api:files.read: “View your basic file information.”
      • For file-service-api:files.write: “Create and modify your files.”
      • For file-service-api:files.read:file_id#file_name: “Allow this app to access and view the file titled {name} only.” (For dynamic scopes, the system might dynamically insert the readable name, or you can craft a general message that works for all instances, depending on implementation.)

  • Importance: A clear and accurate user consent message is critical for building user trust and ensuring transparency in data access.

  • How the User Consent Message is Displayed to End-Users:

    When a third-party developer’s application requests scopes defined here, the end-user will see a consent screen similar to the example below. The “User Consent Message” you provide for each scope will be listed, informing the user exactly what permissions the third party application is seeking.

    Example Consent Screen: Scopes Creation

3. Developer Documentation (Required)

  • Purpose: This field provides a detailed explanation of the scope for application developers who will be integrating with your API. It should offer comprehensive information that helps developers understand when and why to request this specific scope.
  • Input Guidance:
    • Detailed Description: Elaborate on what specific API endpoints or resources this scope grants access to.
    • Affected Data: Clearly state what data types or properties are accessible or modifiable with this scope.
    • Impact of the Scope: Explain the implications of granting this scope (e.g., “Allows the application to fetch all user profiles, including sensitive contact information.”).
    • Usage Examples (Optional but Recommended): Provide code snippets or conceptual examples of how this scope would be used in an API call.
    • Associated Permissions/Limitations: If there are any nuances, dependencies on other scopes, or limitations (e.g., “This scope only grants read access to public profiles”), explain them here.
    • Error Handling: Briefly mention common errors related to scope enforcement for this particular scope.
  • Importance: Good developer documentation reduces integration time, minimizes support requests, and ensures that client applications correctly utilize your API’s permissions system.