Wallaroo MLOps API Essentials Guide: User Management

How to use the Wallaroo API for User Management

Table of Contents

Users

User management provides the ability to create new users, activate/deactivate them and other tasks.

Example Notes

For these examples, we will rely on the wallaroo SDK and requests library for making connections to our sample Wallaroo Ops instance. Examples are provided for both the Python requests library and curl.

import wallaroo

import requests

import json

The Wallaroo SDK provides the API endpoint through the wallaroo.client.api_endpoint variable. This is derived from the Wallaroo OPs DNS settings.

The method wallaroo.client.auth.auth_header() retrieves the HTTP authorization headers for the API connection.

Both of these are used to authenticate for the Wallaroo MLOps API calls used in the future examples. For these examples, the Wallaroo Client is stored in the variable wl.

User Endpoints

Get Users

  • Endpoint: /v1/api/users/query

Users are retrieved either by their Keycloak user id, or return all users if an empty set {} is submitted.

Get Users Parameters

FieldTypeDescription
user_idsList[Keycloak user ids] (Optional)An array of Keycloak user ids, typically in UUID format.

If an empty set {} is submitted as a parameter, then all users are returned.

Get Users Returns

Full details are available from the Keycloak UserRepresentation site. The following represents the most relevant values.

Field  TypeDescription
usersList[user]A list of users and their information with the Keycloak ID as the primary key.
 {keycloak id}userUser details.
  createdTimeTampIntegerThe Unix Epoc Timestamp of when the user was created.
  emailStringThe user’s email address.
  enabledBooleanWhether the user is verified or not.
  firstNameStringThe user’s first name.
  lastNameStringThe user’s last name.
  idStringThe user’s keycloak id in UUID format.
  usernameStringThe user’s username as an email address.

Get Users Examples

The first example will submit an empty set {} to return all users, then submit the first user’s user id and request only that user’s details.

Get all users via Requests.


# Retrieve the token 
headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/users/query"
data = {
}

response = requests.post(endpoint, 
                         json=data, 
                         headers=headers, 
                         verify=True).json()
response
{'users': {'12ea09d1-0f49-405e-bed1-27eb6d10fde4': {'access': {'view': True,
        'manage': True,
        'manageGroupMembership': True,
        'mapRoles': True,
        'impersonate': False},
       'createdTimestamp': 1700496282637,
       'disableableCredentialTypes': [],
       'email': 'john.hummel@wallaroo.ai',
       'emailVerified': False,
       'enabled': True,
       'firstName': 'John',
       'id': '12ea09d1-0f49-405e-bed1-27eb6d10fde4',
       'lastName': 'Hansarick',
       'notBefore': 0,
       'requiredActions': [],
       'username': 'john.hummel@wallaroo.ai'},
      '57d61aed-3058-4327-9e65-a5d39a9718c0': {'access': {'view': True,
        'manage': True,
        'impersonate': False,
        'manageGroupMembership': True,
        'mapRoles': True},
       'createdTimestamp': 1701202186276,
       'disableableCredentialTypes': [],
       'email': 'john.hansarick@wallaroo.ai',
       'emailVerified': True,
       'enabled': True,
       'firstName': 'John',
       'id': '57d61aed-3058-4327-9e65-a5d39a9718c0',
       'lastName': 'Hansarick',
       'notBefore': 0,
       'requiredActions': [],
       'username': 'john.hansarick@wallaroo.ai'},
      '1bc88c6d-b476-4e4d-aa1a-a5a3554591d3': {'access': {'view': True,
        'mapRoles': True,
        'manage': True,
        'manageGroupMembership': True,
        'impersonate': False},
       'createdTimestamp': 1700495081278,
       'disableableCredentialTypes': [],
       'emailVerified': False,
       'enabled': True,
       'id': '1bc88c6d-b476-4e4d-aa1a-a5a3554591d3',
       'notBefore': 0,
       'requiredActions': [],
       'username': 'admin'}}}

Get All Users via curl


curl {wl.api_endpoint}/v1/api/users/query \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    --data '{{}}'
{
  "users": {
    "57d61aed-3058-4327-9e65-a5d39a9718c0": {
      "access": {
        "manage": true,
        "impersonate": false,
        "view": true,
        "manageGroupMembership": true,
        "mapRoles": true
      },
      "createdTimestamp": 1701202186276,
      "disableableCredentialTypes": [],
      "email": "john.hansarick@wallaroo.ai",
      "emailVerified": true,
      "enabled": true,
      "firstName": "John",
      "id": "57d61aed-3058-4327-9e65-a5d39a9718c0",
      "lastName": "Hansarick",
      "notBefore": 0,
      "requiredActions": [],
      "username": "john.hansarick@wallaroo.ai"
    },
    "12ea09d1-0f49-405e-bed1-27eb6d10fde4": {
      "access": {
        "impersonate": false,
        "manageGroupMembership": true,
        "view": true,
        "manage": true,
        "mapRoles": true
      },
      "createdTimestamp": 1700496282637,
      "disableableCredentialTypes": [],
      "email": "john.hummel@wallaroo.ai",
      "emailVerified": false,
      "enabled": true,
      "firstName": "John",
      "id": "12ea09d1-0f49-405e-bed1-27eb6d10fde4",
      "lastName": "Hansarick",
      "notBefore": 0,
      "requiredActions": [],
      "username": "john.hummel@wallaroo.ai"
    },
    "1bc88c6d-b476-4e4d-aa1a-a5a3554591d3": {
      "access": {
        "manage": true,
        "manageGroupMembership": true,
        "mapRoles": true,
        "view": true,
        "impersonate": false
      },
      "createdTimestamp": 1700495081278,
      "disableableCredentialTypes": [],
      "emailVerified": false,
      "enabled": true,
      "id": "1bc88c6d-b476-4e4d-aa1a-a5a3554591d3",
      "notBefore": 0,
      "requiredActions": [],
      "username": "admin"
    }
  }
}

Get first user via Keycloak ID.


# Retrieve the token 
headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/users/query"

# retrieved from the previous request - get the 2nd user since the first will always be `admin`
first_user_keycloak = list(response['users'])[1]

data = {
  "user_ids": [
    first_user_keycloak
  ]
}

user_response = requests.post(endpoint, 
                         json=data, 
                         headers=headers, 
                         verify=True).json()
user_response
{
    'users': {
        '57d61aed-3058-4327-9e65-a5d39a9718c0': {
            'access': {
                'manageGroupMembership': True,
                'mapRoles': True,
                'manage': True,
                'impersonate': False,
                'view': True},
            'createdTimestamp': 1701202186276,
            'disableableCredentialTypes': [],
            'email': 'john.hansarick@wallaroo.ai',
            'emailVerified': True,
            'enabled': True,
            'federatedIdentities': [],
            'firstName': 'John',
            'id': '57d61aed-3058-4327-9e65-a5d39a9718c0',
            'lastName': 'Hansarick',
            'notBefore': 0,
            'requiredActions': [],
            'username': 'john.hansarick@wallaroo.ai'
        }
    }
}

Get first user via curl.


curl {wl.api_endpoint}/v1/api/users/query \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    --data '{json.dumps(data)}'
{
  "users": {
    "57d61aed-3058-4327-9e65-a5d39a9718c0": {
      "access": {
        "manageGroupMembership": true,
        "mapRoles": true,
        "impersonate": false,
        "view": true,
        "manage": true
      },
      "createdTimestamp": 1701202186276,
      "disableableCredentialTypes": [],
      "email": "john.hansarick@wallaroo.ai",
      "emailVerified": true,
      "enabled": true,
      "federatedIdentities": [],
      "firstName": "John",
      "id": "57d61aed-3058-4327-9e65-a5d39a9718c0",
      "lastName": "Hansarick",
      "notBefore": 0,
      "requiredActions": [],
      "username": "john.hansarick@wallaroo.ai"
    }
  }
}

Invite Users

  • Endpoint: /v1/api/users/invite

IMPORTANT NOTE: This command is for Wallaroo Community Edition only. For more details on user management, see Wallaroo User Management.

Users are invited through /users/invite. When using Wallaroo Community, this will send an invitation email to the email address listed. Note that the user must not already be a member of the Wallaroo instance, and email addresses must be unique. If the email address is already in use for another user, the request will generate an error.

Invite Users Parameters

FieldTypeDescription
emailString (Required)The email address of the new user to invite.
passwordString (Optional)The assigned password of the new user to invite. If not provided, the Wallaroo instance will provide the new user a temporary password that must be changed upon initial login.

Invite Users Returns

FieldTypeDescription
idStringThe email address of the new user to invite.
passwordStringThe assigned password of the new user.

Invite Users Examples

Example: In this example, a new user will be invited to the Wallaroo instance and assigned a password.

Invite users via Requests.

headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/users/invite"

data = {
    "email": "example.person@wallaroo.ai",
    "password":"Example-Password"
}

response = requests.post(endpoint, 
                         json=data, 
                         headers=headers, 
                         verify=True).json()
response

Invite users via curl.

curl {wl.api_endpoint}/v1/api/users/invite \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    --data '{{"email": "example.person@wallaroo.ai","password":"Example-Password"}}'

Deactivate User

  • Endpoint: /v1/api/users/deactivate

Users can be deactivated so they can not login to their Wallaroo instance. Deactivated users do not count against the Wallaroo license count.

Deactivate User Parameters

FieldTypeDescription
emailString (Required)The email address user to deactivate.

Deactivate User Returns

{} on a successful request.

Deactivate User Examples

Example: In this example, a user will be deactivated.

Deactivate user via Requests.

# Retrieve the token 
headers = wl.auth.auth_header()

endpoint = f"{wl.api_endpoint}/v1/api/users/deactivate"

data = {
    "email": "john.hansarick@wallaroo.ai"
}

response = requests.post(endpoint, 
                         json=data, 
                         headers=headers, 
                         verify=True).json()
response
{}

Deactivate user via curl.

curl {wl.api_endpoint}/v1/api/users/deactivate \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    --data '{{"email": "john.hansarick@wallaroo.ai"}}'
{}

Activate User

  • Endpoint: /v1/api/users/activate

A deactivated user can be reactivated to allow them access to their Wallaroo instance. Activated users count against the Wallaroo license count.

Activate User Parameters

FieldTypeDescription
emailString (Required)The email address user to activate.

Activate User Returns

{} on a successful request.

Activate User Examples

In this example, the user john.hansarick@wallaroo.ai will be activated.

Activate user via Requests.

# Retrieve the token 
headers = wl.auth.auth_header()
endpoint = f"{wl.api_endpoint}/v1/api/users/activate"

data = {
    "email": "john.hansarick@wallaroo.ai"
}

response = requests.post(endpoint, 
                         json=data, 
                         headers=headers, 
                         verify=True).json()
response
{}

Activate user via curl.

curl {wl.api_endpoint}/v1/api/users/activate \
    -H "Authorization: {wl.auth.auth_header()['Authorization']}" \
    -H "Content-Type: application/json" \
    --data '{{"email": "john.hansarick@wallaroo.ai"}}'
{}

Troubleshooting

When a new user logs in for the first time, they get an error when uploading a model or issues when they attempt to log in. How do I correct that?

When a new registered user attempts to upload a model, they may see the following error:

TransportQueryError: 
{'extensions': 
    {'path': 
        '$.selectionSet.insert_workspace_one.args.object[0]', 'code': 'not-supported'
    }, 
    'message': 
        'cannot proceed to insert array relations since insert to table "workspace" affects zero rows'

Or if they log into the Wallaroo Dashboard, they may see a Page not found error.

This is caused when a user has been registered without an appropriate email address. See the user guides here on inviting a user, or the Wallaroo Enterprise User Management on how to log into the Keycloak service and update users. Verify that the username and email address are both the same, and they are valid confirmed email addresses for the user.