Wallaroo API Guide

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}.

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

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 a Client Secret
• Retrieve MLOps API Token
• Request MLOps Operation with Token

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:

https://magical-rhino-5555.keycloak.wallaroo.dev/auth/admin/master/console/#/realms/master/clients

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

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
print(response.json())