Skip to main content

Machine Users

Machine Users

Create API accounts for bots, scripts, and automations. Machine users enable programmatic access to Webrix without requiring a human identity.

What you can do here​

  • Create and manage machine users for programmatic access
  • Rotate credentials by recreating accounts when needed
  • Configure OAuth2 Client Credentials for enterprise security requirements

Add a machine user​

  1. Click Add Machine User.
  2. Enter a name.
  3. Save to provision credentials within your secure environment.

Using Machine Users​

Machine users support two authentication methods depending on your security requirements.

Without Client Credentials (API Key)​

The simplest approach for internal scripts and trusted environments.

When you create a machine user, Webrix generates an API key automatically. Use this key to authenticate API requests:

curl -H "Authorization: Bearer <YOUR_API_KEY>" \
  https://your-webrix-instance.com/api/...

Best for:

  • Internal automation scripts
  • Development and testing
  • Trusted network environments

With Client Credentials (OAuth2)​

For enterprise environments that require OAuth2 authentication through your Identity Provider (IdP).

Step 1: Enable Client Credentials in Webrix​

  1. Go to Settings → Authentication.
  2. Check Enable Client Credentials for Machine Users.
  3. The Token Endpoint may be auto-detected from your SSO configuration. If not, enter it manually (e.g., https://your-domain.okta.com/oauth2/default/v1/token).
  4. Click Save.

Authentication Settings

Step 2: Configure Client Credentials for a Machine User​

  1. In the Machine Users list, click the three-dot menu (⋮) on your machine user row.
  2. Click Client Credentials.

Machine User Menu

  1. Enter the credentials from your IdP:

    • Client ID: The OAuth2 client identifier
    • Client Secret: The OAuth2 client secret

  2. Click Save.

Now Webrix will use the OAuth2 Client Credentials flow to authenticate this machine user.

Okta Setup for Client Credentials​

This guide explains how to configure Okta to support the OAuth2 Client Credentials flow for machine users.

Prerequisites​

Before you begin, ensure you have:

  • An Okta account with API Access Management enabled
    • Included in Okta Developer (free) accounts
    • Available as an add-on for Okta Workforce Identity
  • Admin access to create applications and configure authorization servers

1. Create an API Services Application​

  1. Log in to your Okta Admin Console.
  2. Navigate to Applications → Applications.
  3. Click Create App Integration.
  4. Select API Services and click Next.

Okta API Services App

  1. Enter a name (e.g., "Webrix Machine User") and click Save.

2. Set Up Authorization Server​

  1. Go to Security → API.
  2. Click on Authorization Servers tab.
  3. You should see a default authorization server. Click on it.

Okta Authorization Servers

info

If you don't see an "Authorization Servers" tab, API Access Management is not enabled in your Okta org. You'll need an Okta Developer account or contact Okta to enable this feature.

3. Create a Scope​

  1. Edit the authorization server, and go to the Scopes tab.
  2. Click Add Scope.
  3. Configure:
    • Name: api.access (or any name you prefer)
    • Description: "Access for machine users"
    • Check Set as a default scope (recommended)
  4. Click Create.

Okta Add Scope

4. Create an Access Policy​

  1. Go to the Access Policies tab.
  2. Click Add Policy.
  3. Configure:
    • Name: "Client Credentials Policy"
    • Description: "Allow client credentials for machine users"
    • Assign to: All clients (or select your specific app)
  4. Click Create Policy.
  5. Inside the policy, click Add Rule.
  6. Configure:
    • Name: "Allow Client Credentials"
    • Grant type: Check Client Credentials
    • Scopes: Any scopes (or select api.access)
  7. Click Create Rule.

5. Get Your Credentials​

  1. Go back to Applications → Applications.
  2. Click on your API Services app (e.g., "Webrix Machine User").
  3. In the General tab, find the Client Credentials section.
  4. Copy the Client ID and Client Secret.

6. Configure in Webrix​

  1. Copy the Token Endpoint from your authorization server: 
    https://{your-okta-domain}/oauth2/default/v1/token
  2. In Webrix Settings → Authentication, paste the Token Endpoint.
  3. In Machine Users, configure your machine user with the Client ID and Client Secret from Okta.

Troubleshooting​

"Feature not enabled" Error​

This means API Access Management is not enabled in your Okta org. Use an Okta Developer account or contact Okta support.

"Invalid scope" Error​

Ensure you've created a scope in your authorization server and either set it as default or request it explicitly.

"Policy evaluation failed" Error​

Create an Access Policy with a rule that allows the Client Credentials grant type.

"Invalid client" Error​

Verify your Client ID and Client Secret are correct and match the application in Okta.