Users API

Users API Overview

The Users API provides comprehensive functionality to manage users in the Aforza platform. You can create, query, update, and manage the lifecycle of users, including their access to Aforza Studio (DAM) and Ava (LLM) applications.

Base URL

All API requests should be made to:

Code
https://api.aforza.com

Authentication

Required Scopes

To access the Users API, you need an auth token with the following scopes:

• users.manage - View, create, update and manage the lifecycle of users

User Lifecycle

Users in the Aforza platform go through the following lifecycle states:

State	Description
PROVISIONED	User has been created and an activation email has been sent to them. Their account is awaiting activation. The user cannot login or access the platform until they have activated their account.
ACTIVE	User has activated their account and can access the platform
INACTIVE	User account has been deactivated. User can no longer log in or access the platform.

Licences

If your tenant has access to Aforza Studio, there will be limit to the number of users that can be assigned Studio.

PROVISIONED and ACTIVE users count towards the licence limit. INACTIVE do not count towards the limit.

User Roles

When creating a user you must set a role of either USER or ADMIN.

User Role	Description
USER	Standard user role
ADMIN	Administrator role with access to the Aforza Admin Portal where admins can manage the tenant and users.

Studio Roles

If assigning Aforza Studio to the user, Studio role must be set.

Studio Role	Description
USER	Standard Studio user
ADMIN	Studio admins can manage the Studio platform and spaces.

Studio Space Roles

Studio space roles only applies if the user has access to Aforza Studio.

Space Role	Description
VIEWER	Read-only access to a space
CONTRIBUTOR	Can contribute content to a space
MANAGER	Can manage content in a space
ADMIN	Full administrative access to a space

Ava Roles

If assigning Ava to the user, Ava role must be set.

Ava Role	Description
USER	Standard Ava user
ADMIN	Admins can manage the Ava platform, including creating prompts, custom agents and custom functions.

Applications

Users can have access to one or more backend applications:

• Aforza Studio - referred to as DAM (Digital Asset Management)
• Ava - referred to as LLM (Large Language Model)

To assign applications to a user, you need to set the backendApplications property to an array of the applications the user has access to.

When creating or updating a user with access to these applications, you must provide the corresponding settings:

• studioSettings - Required if backendApplications includes DAM
• avaSettings - Required if backendApplications includes LLM

Code
{
  ...
  "backendApplications": ["DAM", "LLM"],
  ...
}

Aforza Studio

To create a user with access to Aforza Studio:

Code
{
  ...
  "backendApplications": ["DAM"],
  "studioSettings": {
    "role": "USER",
    "defaultSpaceRole": "VIEWER"
  }
  ...
}

Ava

To create a user with access to Ava:

Code
{
  ...
  "backendApplications": ["LLM"],
  "avaSettings": {
    "role": "USER"
  }
  ...
}

Aforza Studio and Ava

To create a user with access to Aforza Studio and Ava:

Code
{
  ...
  "backendApplications": ["DAM", "LLM"],
  "studioSettings": {
    "role": "USER",
    "defaultSpaceRole": "VIEWER"
  },
  "avaSettings": {
    "role": "USER"
  }
  ...
}

Error Handling

The API returns standard HTTP status codes and error responses in the following format:

Code
{
  "statusCode": 409,
  "error": "Conflict",
  "message": "User with this email address already exists",
  "errorCode": "EMAIL_CONFLICT",
  "field": "emailAddress"
}

Error Codes

Error Code	Description
AVA_NOT_ENABLED	Thrown when trying to assign Ava to a user but Ava is not enabled for the tenant
EMAIL_CONFLICT	Email address is already in use
NO_AVAILABLE_LICENCES	No available licenses for the requested application
SALESFORCE_USER_ID_CONFLICT	Salesforce user ID is already assigned to a different user within your tenant
STUDIO_NOT_ENABLED	Thrown when trying to assign Aforza Studio to a user but Aforza Studio is not enabled for the tenant
STUDIO_SPACE_INFO_REQUIRED	Studio space information is required but missing
THIRD_PARTY_EMAIL_CONFLICT	Email exists in Aforza's third party authentication system

Common HTTP Status Codes

Status Code	Description
200 OK	Request successful
201 Created	Resource created successfully
400 Bad Request	Request validation failed
401 Unauthorized	Invalid or missing authentication token
403 Forbidden	Insufficient permissions
404 Not Found	Resource not found
409 Conflict	Resource conflict (e.g., duplicate email)

Examples

Complete User Creation Example

Code
curl -X POST "https://api.aforza.com/v1/users" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "USER",
    "salesforceUserId": "005000000000000AAA",
    "language": "en-GB",
    "country": "United Kingdom",
    "locale": "en-GB",
    "timeZone": "Europe/London",
    "backendApplications": ["DAM", "LLM"],
    "studioSettings": {
      "role": "USER",
      "defaultSpaceRole": "VIEWER"
    },
    "avaSettings": {
      "role": "USER"
    }
  }'

Query Active Users with Pagination

Code
curl -X GET "https://api.aforza.com/v1/users?status=ACTIVE&limit=25&skip=0&orderBy=lastName" \
  -H "Authorization: Bearer <access_token>"

Search Users by Email

Code
curl -X GET "https://api.aforza.com/v1/users?searchTerm=john@example.com&searchField=emailAddress" \
  -H "Authorization: Bearer <access_token>"

Update User Email and Role

Code
curl -X PATCH "https://api.aforza.com/v1/users/user-123" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "newemail@example.com",
    "role": "ADMIN"
  }'

Best Practices

1. Email Uniqueness: Email addresses must be unique across all tenants in the Aforza platform..

2. Application Settings: Always provide the corresponding settings (studioSettings or avaSettings) when granting access to applications.

3. Pagination: When querying users, use appropriate limit and skip values to handle large result sets efficiently.

4. Error Handling: Always check for error responses and handle them appropriately, especially 409 Conflict errors for duplicate resources.

5. Salesforce Integration: If integrating with Salesforce, ensure the users 18 character salesforceUserId is set.

6. Timezone and Locale: Provide appropriate timeZone, locale, and country values to ensure users have the correct regional settings.