Yotpo User Management API Guide

Auth method: API key + secret (app_key / secret pair exchanged for a short-lived utoken via POST /oauth/token)

Setup steps

1. Log in to the Yotpo dashboard and navigate to Settings > Store Settings > API Credentials.
2. Copy your app_key and secret.
3. POST to https://api.yotpo.com/oauth/token with {"client_id": "", "client_secret": "", "grant_type": "client_credentials"} to receive an access token (utoken).
4. Include the utoken as a query parameter or in the request body on subsequent API calls.

Get access token

• Method: POST
• URL: https://api.yotpo.com/oauth/token
• Watch out for: Tokens are short-lived; cache and refresh before expiry. Expiry duration is not explicitly documented.

Request example

POST /oauth/token
Content-Type: application/json
{
  "client_id": "<app_key>",
  "client_secret": "<secret>",
  "grant_type": "client_credentials"
}

Response example

{
  "access_token": "<utoken>",
  "token_type": "bearer"
}

List account users

• Method: GET
• URL: https://api.yotpo.com/apps/{app_key}/account_users
• Watch out for: Requires a valid utoken. Returns only users associated with the authenticated app_key's account.

Request example

GET /apps/{app_key}/account_users?utoken=<utoken>&page=1&count=10

Response example

{
  "status": {"code": 200},
  "response": {
    "account_users": [
      {"id": 123, "email": "user@example.com", "role": "admin"}
    ]
  }
}

Get single account user

• Method: GET
• URL: https://api.yotpo.com/apps/{app_key}/account_users/{user_id}
• Watch out for: Returns 404 if user_id does not belong to the authenticated account.

Request example

GET /apps/{app_key}/account_users/123?utoken=<utoken>

Response example

{
  "status": {"code": 200},
  "response": {
    "account_user": {"id": 123, "email": "user@example.com"}
  }
}

Create account user

• Method: POST
• URL: https://api.yotpo.com/apps/{app_key}/account_users
• Watch out for: Exact writable fields and role enum values are not fully enumerated in public docs; test against sandbox first.

Request example

POST /apps/{app_key}/account_users
{
  "utoken": "<utoken>",
  "account_user": {
    "email": "newuser@example.com",
    "role": "viewer"
  }
}

Response example

{
  "status": {"code": 200},
  "response": {
    "account_user": {"id": 456, "email": "newuser@example.com"}
  }
}

Update account user

• Method: PUT
• URL: https://api.yotpo.com/apps/{app_key}/account_users/{user_id}
• Watch out for: Full object replacement semantics vs. partial update not explicitly documented; send all desired fields to be safe.

Request example

PUT /apps/{app_key}/account_users/456
{
  "utoken": "<utoken>",
  "account_user": {"role": "admin"}
}

Response example

{
  "status": {"code": 200},
  "response": {
    "account_user": {"id": 456, "role": "admin"}
  }
}

Delete account user

• Method: DELETE
• URL: https://api.yotpo.com/apps/{app_key}/account_users/{user_id}
• Watch out for: Deletion is immediate and irreversible. No soft-delete or deactivation state documented.

Request example

DELETE /apps/{app_key}/account_users/456?utoken=<utoken>

Response example

{
  "status": {"code": 200},
  "response": {}
}

• Rate limits: Yotpo does not publicly document specific numeric rate limits or per-plan tiers in their developer docs. Requests that exceed undisclosed limits return HTTP 429.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No official documentation of rate-limit headers or Retry-After behavior found. Contact Yotpo support for enterprise rate-limit details.

• Pagination method: offset

• Default page size: 10

• Max page size: 100

• Pagination pointer: page / count

• Webhooks available: Yes

• Webhook notes: Yotpo supports webhooks for review and UGC events (e.g., new review submitted, review published). Webhooks are configured in the Yotpo dashboard under Settings > Webhooks. There are no documented webhooks specifically for user/account management events.

• Alternative event strategy: Poll the account_users endpoints periodically to detect user changes, as no user-lifecycle webhooks are documented.

• Webhook events: review_created, review_published, question_created, answer_created

• SCIM available: No
• SCIM version: Not documented
• Plan required: Not documented
• Endpoint: Not documented

Limitations:

• Yotpo does not document a native SCIM 2.0 provisioning endpoint.
• SAML SSO is available for enterprise plans (Okta, Entra ID, OneLogin supported) but automated user provisioning/deprovisioning via SCIM is not documented.
• User lifecycle management must be performed via the REST account_users API or manually through the dashboard.

Three primary automation scenarios are supported by the API:

• Provision a new team member: POST to /oauth/token for a fresh utoken, then POST to /apps/{app_key}/account_users with email and role. Store the returned id for future operations. Role values are undocumented - retrieve existing users first to identify valid strings in your account.

• Deprovision a departing employee: GET /apps/{app_key}/account_users to resolve id by email, then DELETE /apps/{app_key}/account_users/{user_id}. Deletion is immediate and irreversible - no soft-delete state exists. If SAML SSO is active, also disable the user in your IdP; SSO session tokens may remain valid until natural expiry even after API deletion.

• Audit all account users: Paginate GET /apps/{app_key}/account_users?page=1&count=100, incrementing page until the returned array is empty. Collect id, email, role, and created_at per user. Note: offset pagination can return inconsistent results if users are added or removed mid-audit.

Provision a new team member via API

1. POST to /oauth/token with client_id and client_secret to obtain a utoken.
2. POST to /apps/{app_key}/account_users with the new user's email and desired role in the request body.
3. Store the returned user id for future update or deletion operations.
4. Optionally verify by GET /apps/{app_key}/account_users/{user_id}.

Watch out for: Role enum values are undocumented; retrieve existing users first to identify valid role strings in your account.

Deprovision a departing employee

1. Obtain a fresh utoken via POST /oauth/token.
2. GET /apps/{app_key}/account_users to find the target user's id by email.
3. DELETE /apps/{app_key}/account_users/{user_id} to remove the user.
4. If SAML SSO is in use, also disable the user in your IdP (Okta/Entra/OneLogin) to revoke SSO access.

Watch out for: Deleting via API removes the user immediately with no recovery option. SAML SSO session tokens may remain valid until expiry even after API deletion; IdP-side deactivation is required for immediate access revocation.

Audit all account users

1. Obtain a utoken via POST /oauth/token.
2. GET /apps/{app_key}/account_users?page=1&count=100 to retrieve the first page.
3. Increment page parameter and repeat until the returned account_users array is empty or fewer than count.
4. Collect id, email, role, and created_at fields for each user for your audit log.

Watch out for: No cursor-based pagination; offset pagination with large datasets may return inconsistent results if users are added/removed mid-audit.

The primary integration trap is token lifecycle management. The utoken is short-lived with no publicly documented expiry duration - failing to refresh before a batch operation will produce auth failures mid-run. Implement refresh logic defensively before every significant API call sequence.

Rate limits are entirely undocumented. There are no rate-limit headers, no Retry-After guidance, and no per-plan tiers published. Aggressive polling - for example, continuous user-change detection in the absence of user-lifecycle webhooks - risks silent throttling or 429 responses with no recovery signal.

Webhooks exist for review/UGC events only; there are no webhooks for user creation, update, or deletion, so polling /account_users is the only available change-detection mechanism.

For teams using an MCP server with 60+ deep IT/identity integrations to maintain a unified identity graph, Yotpo's lack of SCIM and undocumented role schema means the integration layer must handle role normalization and token refresh explicitly - these are not abstracted by the API itself.