Understanding scopes

In the world of API integrations and OAuth, scopes play a crucial role in managing access to resources. This guide explains the concept of scopes, their importance in OAuth, and how they are handled specifically at Unified.to.

What are scopes?

Scopes are a way to limit an application's access to a user's account. Instead of granting complete access to an account, scopes allow for fine-grained permission control.

Think of scopes as permission slips. When you use an app that integrates with another service (like signing in with Google), scopes define exactly what that app is allowed to do with your account. It's like telling the bouncer at a club, "This person can enter the main area, but not the VIP lounge."

Why are scopes important?

  1. Security: Scopes ensure that applications only have access to the specific data and actions they need, reducing the risk of unauthorized access.
  2. User Control: Users can make informed decisions about what access they're granting to applications.
  3. Compliance: Scopes help applications adhere to data protection regulations by implementing the principle of least privilege.

How scopes work in OAuth

In the OAuth flow:

  1. An application requests one or more scopes.
  2. The user is presented with these scope requests during the authorization process.
  3. If the user approves, an access token is issued that's limited to the approved scopes.

For example, an application might request the scope https://www.googleapis.com/auth/drive.readonly to read files from Google Drive, but not edit or delete them.

Scopes at Unified.to

Unified.to acts as a conduit between your application and various API providers. We use a unified set of scopes that map to provider-specific scopes. This abstraction simplifies the integration process across multiple providers.

Unified scopes

Unified.to uses its own set of scopes, which are then mapped to provider-specific scopes. For example:

  • storage_file_read maps to https://www.googleapis.com/auth/drive.readonly for Google Drive
  • crm_company_read maps to oauth, crm.objects.owners.read, crm.objects.companies.read for HubSpot

You may notice that some Unified scopes map to multiple provider-specific scopes. This is done to ensure that all the necessary permissions are requested for the integration to function correctly.

The mappings for all scopes are found under their respective Integration page at app.unified.to under OAuth 2 Credentials e.g. here are the mappings for Google Drive.

Provider-specific scopes

When setting up your developer account and/or developer app, you will need to define your scopes with the API providers themselves - Unified.to is unable to do this for you. How this is done varies on a case-by-case basis, but it is usually configured while generating your OAuth credentials. We have several how-to guides for generating credentials and setting scopes for our most popular integrations. If you think any are missing, please let us know.

Requesting scopes

When using Unified.to, you can request scopes in one of two ways, depending on how you intend to authorize your users:

  1. (Recommended) Using the Authorization component: On app.unified.to, you can select the scopes you need under Embedded components > Authorization (scroll down to Options)).
  2. Using the Authorization URL: When generating an auth URL, you can include the scopes as a query parameter. For example:
    https://api.unified.to/unified/integration/auth/{WORKSPACE_ID}/{INTEGRATION}?redirect=true&scopes=webhook,crm_deal_read,crm_event_read

Note: If you do not specify any scopes at all, then Unified.to will attempt to request all the scopes available for the integration. We strongly advise you to consider which scopes you actually need and then intentionally specify them using one of the above two methods. The next section will go over best practices when requesting scopes.

Best practices for scope usage

  1. Request Only What You Need: Always request the minimum set of scopes required for your application to function.
  2. Check Provider Requirements: Some providers may require certain scopes to always be enabled. Check the Unified.to documentation for provider-specific requirements.
  3. Include the Webhook Scope: If you're setting up webhooks, always include the webhook scope in your requests.
  4. Verify Scope Mappings: You can view the mapping of Unified.to scopes to provider-specific scopes in the Unified.to dashboard for each integration.

Conclusion

Understanding and correctly implementing scopes is crucial for secure and efficient API integrations. By leveraging Unified.to's scope system, you can simplify the process of working with multiple providers while maintaining granular control over access permissions.

Are we missing anything? Let us know
Was this page helpful?