This topic presents recommended practices for configuring API access, selecting the right credentials for your organization access needs, and managing authentication efficiently, with additional guidance to be added over time.
Apply these best practices when you first build an integration with Clean Room APIs, and revisit them if calls begin returning errors.
Use One API Key per User or Application
LiveRamp Clean Room supports one API key per user or application, and multiple API keys per organization. When you generate an API key, Clean Room creates an API user for it at the address api-user-{client_id}@habu.com and assigns it the API Administrator role. That API user belongs to the organization where you generated the key.
Add the API user only to clean rooms within that same organization. Adding it to a second organization creates a conflict in the backend authorization mapping, and the API begins rejecting calls made with that credential.
Cross-organization API users return 403When one API user belongs to more than one organization, calls such as
GET /v1/cleanrooms/{cleanroomId}/destinationsreturn403 Forbiddeneven though the API user holds every permission on the clean room. Granting more permissions does not resolve it. The cause is the credential's organization scope.
To resolve or avoid the problem:
- Generate a separate API key in each organization that needs API access. For more information,
see "Configuring a Clean Room API User". - Update your scripts to use the client ID and secret belonging to the organization they call.
- Remove the API user from any other organization, and then rotate or delete the unused secret on
the Manage API Key page.
If your integration needs a single credential that reaches more than one organization, use an API service account.
Choose the Right Credential for Multi-Organization Access
| Credential | Scope | Use it when | How to get it |
|---|---|---|---|
| Clean Room API key | One Clean Room organization | Your integration works within a single organization. | In the Clean Room main menu, select Admin → API Keys. |
| LiveRamp API Service Account | Multiple Clean Room organizations | Your integration must reach more than one organization. | Contact your LiveRamp representative. |
For the credential setup these recommendations depend on, see "Configuring a Clean Room API User" and "Request an Access Token".
Cache Access Tokens Until They Expire
An access token from /v1/oauth/token is valid for 12 hours, and the expiresAt field in the
token response gives its exact expiration time. LiveRamp also limits token requests to two per
24-hour period for each credential.
Request a token once, store it, and send it with every subsequent call until it expires.
Requesting a new token for each API call exhausts the daily allowance within the first few calls,
after which LiveRamp rejects further token requests and your integration stops working for the
rest of the period.
In your client:
- Read
expiresAtfrom the token response and keep the token until that time passes. - Request a replacement token when the current one expires or when a call returns
401. - Share one cached token across the threads and processes that use the same credential.
Design for Rate Limits
The Clean Room API limits how many requests you can make, which protects the API and the systems
behind it. LiveRamp applies these limits per API user, organization, and IP address, so several
clients sharing one credential draw down the same allowance.
Build these behaviors into your client:
- Throttle your request rate to the level your workflow actually needs.
- Handle
429 Too Many Requestswith exponential backoff, and wait out the current window before
retrying. - Poll for an object's status on a fixed schedule. Hourly polling is enough for most workflows.
- Give question runs and flow runs distinct, meaningful names so you can identify which run failed
without repeating it.
The Clean Room API enforces a per-hour limit on the calls that create question runs and flow runs,
and a daily limit on access token requests. For the current values and the endpoints they apply
to, see "API Limits".
FAQs
Q. Can I use one Clean Room API key across multiple organizations?
A. No. Clean Room supports one API key and one API user per organization, and that API user
belongs to the organization where you generated the key. To reach more than one organization with a
single credential, use a LiveRamp API Service Account.
Q. Why do I get a 403 error when the API user has every permission granted?
A. The 403 indicates a conflict in the credential's organization scope. If the API user for your
client ID has been added to more than one organization, the backend authorization mapping
conflicts, and calls fail with 403 Forbidden. Generate a new API key in the single organization
you are calling, and use its client ID and secret.
Q. How do I find out which organizations an API user belongs to?
A. Check the user list in each organization: select Admin → Users and look for the address
api-user-{client_id}@habu.com. Clean Room has no single view listing every organization an API
user belongs to, so contact LiveRamp Support if you need help tracing one.
Q. What do I do if my API key is already in more than one organization?
A. Generate a new API key in the organization you want the integration to use, update your scripts
with the new client ID and secret, remove the old API user from the other organizations, and then
rotate or delete the old secret on the Manage API Key page. A key scoped to one organization
returns 200 on calls that previously failed with 403.
Q. How many access tokens can I request per day?
A. Two per 24-hour period. Each token is valid for 12 hours, so two tokens cover a full day of
continuous use as long as you cache and reuse them.
Q. Do rate limits apply per API key or per organization?
A. Both. LiveRamp manages limits per API user, organization, and IP address, so separate scripts
that share a credential or an IP address count against the same limit.