Scoping OAuth client to specific divisions for multi-tenant BPO access in Kotlin

NICE CXone API & Integrations
1

We’re building an Android app using the Genesys Cloud Kotlin SDK (genesys-cloud-auth and genesys-cloud-platform) for a BPO client. The setup involves multiple tenants, and we need to ensure that the OAuth client created for our app only accesses resources within specific divisions. Currently, when we authenticate, the token seems to have access to all divisions associated with the user, which isn’t what we want. We want to restrict access to just the divisions relevant to the current tenant context.

I’ve been looking at the /api/v2/authorization/clients endpoint and the OAuthClient model in the SDK, but I don’t see an obvious way to specify division IDs during client creation or token acquisition. The documentation mentions scopes, but those seem to be about permissions (like chat:read), not division-level filtering.

Here’s the relevant part of our Kotlin code for client creation:

val client = OAuthClient(
 name = "BPO App Client",
 description = "Client for multi-tenant BPO access",
 grantTypes = listOf("client_credentials"),
 redirectUris = listOf("https://our-app.com/callback")
)
val response = authApi.createOAuthClient(client)

And for token acquisition:

val tokenResponse = authApi.generateOAuthToken(
 OAuthTokenRequest(
 grantType = "client_credentials",
 clientId = client.id,
 clientSecret = client.secret
 )
)

Is there a way to pass division IDs or a tenant context when creating the client or requesting the token? Or do we need to handle this filtering on our backend after getting the token? Any code examples or API parameters I’m missing would be appreciated.

2

Here is how I handle division scoping in my automation scripts, which might translate to your Kotlin setup. The OAuth token itself doesn’t carry division limits; it’s the API client initialization that needs the filter.

  • Set the division ID explicitly on the client. In the Java/Kotlin SDK, you don’t just pass the token. You need to configure the PlatformClient with the specific division ID before making calls. If you leave it null, it defaults to the user’s home division or all divisions depending on the endpoint.
  • Use the setDivisionId method. After building your PlatformClient instance, call client.setDivisionId("your-target-division-id"). This ensures every subsequent API call for that client instance includes the X-Genesys-Organization-Id and division headers correctly.
  • Verify the division ID first. Before hardcoding it, grab the list of divisions for the user to confirm the exact ID. You can use this snippet to check:
val client = PureCloudPlatformClientV2.Builder()
 .withClientId("your-client-id")
 .withClientSecret("your-client-secret")
 .build()

// Get user details to find valid divisions
val userApi = client.userApi
val user = userApi.getUserById("user-id")
println("Home Division: ${user.homeDivision.id}")
  • Handle multi-tenant logic carefully. If you truly have separate tenants, you might need separate OAuth clients per tenant. Division scoping works within a single tenant. If you’re mixing tenants, check your OAuth app’s allowed origins and ensure the token is scoped to the correct organization.
  • Test with a restrictive role. Create a test user with a role that only has access to the target division. Authenticate as that user. If the app still accesses other divisions, your client configuration is ignoring the division filter. Double-check that you aren’t overriding the division ID in individual API calls.

The SDK handles the heavy lifting for headers, but you have to tell it which division to target. Don’t assume the token carries the context.