Cloud API Resources

briancoombs · ‎05-13-2024

Overview

This is quick guide to using the Alteryx Analytics Cloud (AAC) Application Programming Interface (API). For detailed instructions and documentation, go to AAC to access the full API Specification based on your region...

Why Use APIs

You can accomplish many tasks programmatically using AAC APIs. This can be useful to execute a long series of commands that might otherwise be tedious to perform using the AAC User Interface (UI). Alternatively, you can automate and schedule tasks as needed using these APIs. These are a couple of examples of how you might use the AAC APIs:

Invite a batch of users to join AAC.
Revoke access for a batch of users.
Run a plan, flow, or job triggered by an event or events.
Create a batch of data connections.

API Overview

You can use a third-party client, such as curl, HTTPie, Postman, or the Insomnia rest client to test the AAC API.

When testing the API, you are working with your live production data. Changes you make have immediate effects on your production AAC environment.

For example, here is how to list all of your access tokens using curl:

curl -X GET 'https://us1.alteryxcloud.com/v4/apiAccessTokens' \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer <token>'

These are the key items to pay attention to in this request:

The header for Content-type has been set to application/json. AAC requires this for nearly all of its APIs.
Authentication is by Bearer token. Replace <token> with your own token. Note that you shouldn’t include <> with your token.

After you replace the token value with your own, execute the above command. The result might look like this:

{
  "data": [
    {
      "tokenId": "<your tokenID>",
      "description": "The description of your token",
      "createdAt": "The date the token was created",
      "expiredAt": "The date the token will expire",
      "lastUsed": "Likely the current time",
      "person": {
        "name": "Your Name",
        "email": "Your email",
        "id": <your id>
      }
    }
  ]
}

Tokens

Ensure the security of your access tokens. Anyone with your token can use AAC APIs as though they are you.

There are currently 2 types of tokens: legacy static Access tokens which will be deprecated and OAuth 2.0 API tokens.

The new OAuth 2.0 API tokens are dynamic and provide improved security and control when compared to the legacy API tokens.

If you are a current user of the legacy API tokens created on the Access Tokens Page, please migrate to the new OAuth 2.0 API tokens. The legacy API tokens have been deprecated and new tokens created on the Access Tokens Page are not supported.

Note that the last date to migrate to the new API tokens is July 11, 2024.

Here is a guide to creating and refreshing the OAuth 2.0 API Tokens.

Here is a guide to creating the legacy static Access tokens. Not this is not recommended unless absolutely necessary.

A Simple Example Using APIs

Here is an example of how you might use the AAC APIs in day-to-day use. Say you want to invite a list of users to use AAC. Specifically, you want to invite them to a workspace.

First, you need to get the workspace ID that you are inviting users to:

curl -X GET 'https://us1.alteryxcloud.com/v4/workspaces' \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer <token>'

That should return JSON similar to:

[
  {
    "id": 123,
    "name": "workspace1",
    "state": "active",
    "lastStateChange": null,
    "deleted_at": null,
    "custom_url": "url",
    "max_user_number": 100,
    "emrConfigId": null,
    "createdAt": "date",
    "updatedAt": "date",
    "workspacetiers": [
      {
        "isSingleUser": false,
        "id": 123,
        "name": "name",
        "workspaceId": 123,
        "startsAt": "date"
      }
    ]
  },
  {
    "id": 456,
    "name": "workspace1",
    "state": "active",
    "lastStateChange": null,
    "deleted_at": null,
    "custom_url": "url",
    "max_user_number": 100,
    "emrConfigId": null,
    "createdAt": "date",
    "updatedAt": "date",
    "workspacetiers": [
      {
        "isSingleUser": false,
        "id": 456,
        "name": "name",
        "workspaceId": 456,
        "startsAt": "date"
      }
    ]
  }
]

Pick out the workspace you want to invite the users to and note its ID. For this example, use the <id> value for one of the workspaces.

Next, invite new users to this workspace with this example:

Be sure to fill in your workspace ID for <id> and your token for <token>.

curl -X POST 'https://us1.alteryxcloud.com/v4/workspaces/<id>/people/batch' \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{"emails": ["name1@domain.com", "name2@domain.com>"]}'

At this point, curl doesn’t display anything on success. By default, curl only shows the response body. Add -v to the above command for verbose output.

Congratulations you’ve now added users to a workspace! If the above command executed successfully, your new users will receive emails inviting them to join AAC.