Wallaroo API Guide

Reference Guide for the Wallaroo API

The Wallaroo API provides users the ability to commands to a Wallaroo instance via a RCP-like HTTP API interface. This allows organizations to develop applications that can administrate Wallaroo from their own custom applications.

Wallaroo API URLs

Each instance of Wallaroo provides the Wallaroo API specifications through the following URLs. Wallaroo uses the following format for its URLs. For more information, see the DNS Integration Guide.

https://{Wallaroo Prefix}{Service}{Wallaroo Suffix}.

Page URL Description
Wallaroo Instance API URL https://{Wallaroo Prefix}.api.{Wallaroo Suffix}/v1/api Address for the Wallaroo instance’s API. API requests will be submitted to this instance.
Wallaroo Instance API Documentation https://{Wallaroo Prefix}.api.{Wallaroo Suffix}/v1/api/docs A HTML rendered view of the Wallaroo API specification.
Wallaroo Documentation Site https://docs.wallaroo.ai/ Wallaroo Documentation Site
Wallaroo Enterprise Keycloak Service https://{Wallaroo Prefix}.keycloak.{Wallaroo Suffix} Keycloak administration console for managing users and groups. It is recommended not to interfere with this service unless necessary.
Wallaroo Enterprise Token Request URL https://{Wallaroo Prefix}.keycloak.{Wallaroo Enterprise Suffix}/auth/realms/master/protocol/openid-connect/token The Keycloak token retrieval URL.

For example, if the Wallaroo Enterprise Prefix is wallaroo and the suffix is example.com, the URLs would be as follows:

Page Example URL
Wallaroo Instance API URL https://wallaroo.api.example.com/v1/api
Wallaroo Instance API Documentation https://wallaroo.api.example.com/v1/api/docs
Wallaroo Documentation Site https://docs.wallaroo.ai/
Wallaroo Enterprise Keycloak Service https://wallaroo.keycloak.example.com
Wallaroo Token Request URL https://{Wallaroo Prefix}.keycloak.example.com/auth/realms/master/protocol/openid-connect/token

Authenticating to the Wallaroo API

Each MLOps API operation requires a valid JSON Web Token (JWT) obtained from Wallaroo’s authentication and authorization service (i.e., Keycloak). Generally, the JWT must include a valid user’s identity, as Wallaroo access permissions are tied to specific platform users.

To authenticate to the Wallaroo API, the options are either to authenticate with the client secret, or to use the SDK command Wallaroo.auth.auth_header() to retrieve the HTTP header including the token used to authenticate to the API.

The following process will retrieve a token using the client secret:

Retrieve Client Secret

Wallaroo comes pre-installed with a confidential OpenID Connect client. The default client is api-client, but other clients may be created and configured.

As it is a confidential client, api-client requires its secret to be supplied when requesting a token. Administrators may obtain their API client credentials from Keycloak from the Keycloak Service URL as listed above and the prefix /auth/admin/master/console/#/realms/master/clients.

For example, if the Wallaroo instance DNS address is https://magical-rhino-5555.wallaroo.dev, then the direct path to the Keycloak API client credentials would be:


Then select the client, in this case api-client, then Credentials.

Wallaroo Keycloak Service
Wallaroo Components

By default, tokens issued for api-client are valid for up to 60 minutes. Refresh tokens are supported.

Retrieve MLOps API Token

To retrieve an API token for a specific user with the Client Secret, request the token from the Wallaroo instance using the client secret and provide the following:

  • Token Request URL: The Keycloak token retrieval URL.
  • OpenID Connect client name: The name of the OpenID Connect client.
  • OpenID Connect client Secret: The secret for the OpenID Connect client.
  • UserName: The username of the Wallaroo instance user, usually their email address.
  • Password: The password of the Wallaroo instance user.

For example, the following requests a token for the Wallaroo instance https://magical-rhino-5555.wallaroo.dev for user mary.jane@example.com with the OpenID Connect Client api-client:

TOKENURL = 'https://magical-rhino-5555.keycloak.wallaroo.dev/auth/realms/master/protocol/openid-connect/token'
CLIENT ='api-client'
SECRET = 'abc123'
USERNAME = 'mary.jane@example.com'
PASSWORD = 'snugglebunnies'

TOKEN=$(curl 'https://magical-rhino-5555.keycloak.wallaroo.dev/auth/realms/master/protocol/openid-connect/token' -u "$CLIENT:$SECRET" -d "grant_type=password&username=$USERNAME&password=$PASSWORD" -s | jq -r '.access_token')

Request MLOps Operation with Token

With the token retrieve, a MLOps request can be performed.

The following example shows how to make the request using curl to retrieve a list of workspaces:

curl 'https://magical-rhino-5555.api.wallaroo.ai/v1/api/workspaces/list' -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{}'

The same can be done through the Python requests library:

## Inference through external URL

apiRequest = "https://magical-rhino-5555.api.wallaroo.ai/v1/api/workspaces/list"

# set the headers
headers= {
        'Authorization': 'Bearer ' + TOKEN,
        'Content-Type: application/json'

data = {

# submit the request via POST
response = requests.post(apiRequest, data=data, headers=headers)

# Display the returned result