Skip to main content

Service Principals

Note

This feature is in Public Preview.

In this release, service principals can be used to configure and run workflows with AI Tools on Server. To learn more, go to Use AI Tools on Server.

Functionality and user experience might evolve as we continue to enhance and refine the experience.

Service Principals are non-human identities that allow automated processes to securely access Alteryx One without relying on individual users.

This is especially important in regulated environments, where user-based automation and credential sharing introduce risk.

Prerequisites

  • Service Principals are available in the Enterprise Edition. For more information, go to Enterprise Edition Capabilities.

  • You must be assigned the Workspace Admin role, or a custom role that includes the Service Principals capability. For more information, go to Custom Roles.

Create

Create a service principal to enable secure, non-human access to this workspace.

  1. Select New.

  2. Enter a Name. This is how the service principal is identified within the workspace.

  3. (Optional) Enter a Description. This is visible to other administrators.

  4. Use the Lifetime (Days) dropdown to define how long the client secret remains valid.

  5. Use the Roles dropdown to assign access.

    Service principals have no access by default.

    Tip

    To minimize risk, create and assign a custom role that only includes the permissions required for the intended use case.

  6. Select Create.

  7. A dialog displays the service principal credentials:

    • Token Endpoint 

    • Client ID 

    • Client Secret 

    Warning

    Copy and store the Client Secret securely.

    You will not be able to view the Client Secret again after closing this dialog.

Retrieve an Access Token

To authenticate as a service principal, request an access token from Alteryx One’s Token Endpoint using the service principal’s client credentials.

Request

Send a POST request to the Token Endpoint:

POST https://<your-base-url>/as/token

Headers

Content-Type: application/x-www-form-urlencoded

Body (x-www-form-urlencoded)

Key

Value

grant_type

client_credentials

client_id

<Client ID>

client_secret

<Client Secret>

Example

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Response

The response includes an access token:

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 300
}

Use the access_token to authenticate API requests:

Authorization: Bearer <ACCESS_TOKEN>

Edit

You can edit a service principal and update its access in either of the following ways:

  • From the Service Principals page, select the 3-dot menu next to the service principal, then select Edit Service Principal.

  • From the Service Principals page, select a service principal to open its details page, then select Edit.

Update the required fields, then select Save.

Disable

You can disable a service principal in either of the following ways:

  • From the Service Principals page, select the 3-dot menu next to the service principal, then select Disable.

  • From the Service Principals page, select a service principal to open its details page, then select Disable Service Principal.

When disabled, the service principal can no longer authenticate or run processes. Its assigned access and owned assets are preserved.

Delete

You can delete a service principal in either of the following ways:

  • From the Service Principals page, select the 3-dot menu next to the service principal, then select Delete.

  • From the Service Principals page, select a service principal to open its details page, then select Delete Service Principal.

In the confirmation dialog, enter DELETE to confirm the action.

Select Delete.

Warning

Deleting a service principal will disrupt external processes that rely on it, including automated workflows or integrations.

Secret Rotation

Service principals can have up to 2 active secrets at a time, allowing you to generate a new secret before removing the old one. This reduces downtime when performing maintenance.

Generate New Secret

  1. From the Service Principals page, select a service principal to open its details page.

  2. Select Generate Secret.

  3. Copy and securely store the new secret.

When a new secret is generated, the existing secret will remain valid for up to 30 days or until its original expiration date, whichever comes first.

Tip

To avoid disruptions, make sure all external processes using the service principal are updated with the new secret before deleting the old secret or allowing it to expire.

Delete Old Secret

If a service principal has 2 active secrets, you can optionally delete the old secret after updating your external systems.

From the service principals details page, select the 3-dot menu next to Rotate Secret, then select Delete.

This option is only available when 2 secrets are present.

Usage

  • Assigning a role to a service principal does not consume a user seat.

  • When a service principal runs a workflow, it consumes an Automated Run.

Audit Events

Actions performed by service principals appear in the Audit Log with:

agent_type = SERVICE_PRINCIPAL 

In this section: