Wallaroo MLOps API Essentials Guide: User Management

How to use the Wallaroo API for User Management

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

Field	Type	Description
user_ids	List[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			Type	Description
users			List[user]	A list of users and their information with the Keycloak ID as the primary key.
	`{keycloak id}`		user	User details.
		createdTimeTamp	Integer	The Unix Epoc Timestamp of when the user was created.
		email	String	The user’s email address.
		enabled	Boolean	Whether the user is verified or not.
		firstName	String	The user’s first name.
		lastName	String	The user’s last name.
		id	String	The user’s keycloak id in UUID format.
		username	String	The 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

Field	Type	Description
email	String (Required)	The email address of the new user to invite.
password	String (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

Field	Type	Description
id	String	The email address of the new user to invite.
password	String	The 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

Field	Type	Description
email	String (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

Field	Type	Description
email	String (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.