Data Scopes Guide for HRIS Connectors

Control which fields your application can access via the unified API. Data Scopes enforce field-level permissions on READ & WRITE operations, improving security and performance. And they also enforce which fields of the data you are allowed to write on the connector.

Note: Data Scopes are currently available only for the HRIS & Accounting APIs. This guide covers the HRIS APIs. For Accounting, see the Accounting Data Scopes Guide.

Why Data Scopes

When you integrate HRIS data, you rarely need every field. A scheduling app doesn't need employee SSNs. A reporting dashboard doesn't need home addresses.

Data Scopes solve this:

• Request only what you need - Connectors that support field selection will only fetch specified fields from downstream APIs
• Enforce least privilege - Your application cannot access fields outside the configured scope
• Simplify compliance - Document exactly which employee data your integration touches

When a connector doesn't support native field filtering, Apideck strips non-scoped fields from the response before returning data. Your app never sees them.

How It Works

Data Scopes operate at two levels:

• Application level: You define which fields your app can request across all consumers. Configure this in the Apideck dashboard.
• Consumer level: Each consumer must grant access to scoped fields before their connection becomes active. If you expand the scope later, consumers must re-consent.

Enabling Data Scopes

1. Go to Configuration > Data Scopes in your Apideck dashboard
2. Select HRIS from the Enabled APIs list
3. Toggle Enable data scopes
4. Expand a resource (Employees, Departments, Companies, Time Off Requests) to see available fields
5. Check the fields you need for Read and/or Write operations
6. Click Save Changes

The field list shows only fields supported by your enabled connectors. If you don't see a field, enable more connectors first.

Consumer Consent Flow

When Data Scopes are enabled, consumers see a consent screen before their connection becomes callable. This is managed through Vault:

1. Consumer opens Vault to configure their HRIS connection
2. After authorization, they see the Requested Data Access prompt
3. The prompt lists exactly which fields your app wants to access
4. Consumer clicks Accept to grant access, or Deny to reject

If you change the scope configuration (e.g., by adding new fields), existing consumers must re-consent before requests succeed.

What Happens When Data Scopes Are Enabled

Read operations (employeesAll, employeesOne, etc.):

• Apideck requests only granted fields from the connector (when supported and mapped)
• Response contains only granted fields, regardless of connector support
• Logs show only granted fields

Write operations (employeesAdd, employeesUpdate, etc.):

• Requests containing non-granted fields are rejected
• You'll receive a validation error before the request reaches the downstream API

Viewing Consent History

Track when consumers granted or revoked access:

Via Dashboard:

1. Go to Consumers in your dashboard
2. Select a consumer
3. Click on a connection (e.g., BambooHR)
4. Select Consent History from the menu

Via API: Use the Get consent records endpoint to retrieve consent history programmatically.

Example: Limiting Employee Data Access

Say you're building a team directory app. You only need basic employee info, not sensitive data.

Configure these fields for the Employees resource:

• id
• first_name
• last_name
• display_name
• title
• department
• department_name
• manager
• employment_status
• photo_url

Leave unchecked:

• social_security_number
• date_of_birth
• gender
• marital_status
• home address fields
• compensation fields
• bank account fields

Now your API responses will never contain sensitive PII, even if the downstream HRIS returns it.

API Behavior

When a consumer hasn't granted access to Data Scopes, API requests will fail. The consumer must complete the consent flow in Vault before their connection becomes callable. Check the connection state using the Vault API to determine if consent is pending. If state is not callable, prompt your users to complete the consent flow.

Best Practices

• Start minimal: Enable only the fields you actually use. You can always expand later.
• Group by use case: If different features need different fields, consider separate Apideck applications with distinct scope configurations.
• Document your scopes: Keep a record of why each field is needed. This helps with compliance audits and onboarding new team members.
• Handle re-consent gracefully: When you expand scopes, existing consumers must re-consent before requests succeed. Build UI to guide them back to Vault.

FAQ

What if a connector doesn't support field selection? Apideck still filters the response. The connector returns all fields, but Apideck strips any fields that are not granted before sending the data to your application. Your app never sees unauthorized data.

Do Data Scopes affect write operations? Yes. Write requests containing non-granted fields are rejected with a validation error. Only include fields within your configured scope.

What about nested objects? You can scope fields within nested objects. For example, you might allow jobs.title and jobs.department while excluding jobs.compensation_rate.

Can I use different scopes for different resources? Yes. Each resource has its own scope configuration. A team directory app might have broad read scopes on Employees but no access to Time Off Requests at all.

What happens to existing consumers when I enable Data Scopes? They must grant access before making API requests. Until they consent, the connection won't be callable.

Can consumers see which fields I'm requesting? Yes. The consent screen shows the exact fields and resources your application wants to access. Transparency is the point.