Get Started with the Agentforce Operations REST API

Use the Agentforce Operations REST API to access and manage workspace resources, such as blueprints, workflows, and users. This guide shows you how to set up authentication and make an API call.

Prerequisites 

Before you begin:

  • You have an active Agentforce Operations workspace.
  • You have an Admin role in your Agentforce Operations workspace.

Overview 

All REST API calls to your Agentforce Operations workspace require two values: an OAuth access token and a workspace UUID. Get the OAuth access token by using a service account’s client ID and client secret. Access tokens expire after 2 hours. Find your workspace UUID in your browser’s developer tools.

This guide walks you through:

  1. Creating a service account and saving its credentials
  2. Finding your workspace UUID
  3. Requesting an OAuth access token
  4. Making your first API call

Create a Service Account 

A service account is a dedicated API-only user in your Agentforce Operations workspace. Unlike a regular user account, a service account authenticates programmatically by using a client ID and client secret rather than a username and password. To create the account, use your admin session credentials. After you create it, you use the service account’s client ID and client secret to request OAuth access tokens for all REST API calls.

  1. Get your session bearer token.

    1. Log in to your Agentforce Operations workspace in a browser.

    2. Open your browser’s developer tools and click the Console tab.

    3. To get your session bearer token, enter this command:

      Get Your Session Bearer Token
      1"Bearer " + JSON.parse(localStorage.getItem('_auth0_user'))['token']

    4. Copy the returned bearer token, including the Bearer prefix.

  2. Create the service account and get its client ID and client secret.

    1. Open the GraphiQL playground at your workspace’s /playground path. Go to https://<your-instance>.regrello.salesforce.com/playground, replacing <your-instance> with your tenant prefix.

    2. In the Headers section, add your bearer token:

      Set the Authorization Header
      1{
2   "Authorization": "<your-bearer-token>"
3}

    3. Refresh the browser window.

    4. In the query pane, enter and run this mutation. Replace the name value with a name for your service account.

      Create the Service Account
      1mutation {
2  createServiceAccountUser(input: {
3    accessLevel: INTERNAL,
4    name: "Your Service Account Name",
5  }) {
6    user {
7      id
8      email
9      name
10    }
11    clientId
12    clientSecret
13  }
14}

      The response includes your service account’s clientId and clientSecret.

    5. Copy and save your client ID and client secret in a secure location such as a password manager. You use this information each time you get an access token. An access token expires after 2 hours.

      You can’t view the client ID or client secret after you leave the GraphiQL page. If you lose either credential, you must create another service account to get new credentials.

      Important

    6. To view and manage your workspace’s service accounts, in the navigation panel, select Admin, click the People tab, and use “service-account” as the filter.

      You can edit a service account’s details or deactivate it, but you can’t view its client ID or client secret again.

      Note

Find Your Workspace UUID 

Every API call requires your workspace UUID.

  1. Open your Agentforce Operations workspace in a browser.

  2. Open your browser’s developer tools. Press F12 (Windows) or Command+Option+I (Mac).

  3. Click the Network tab.

  4. Refresh the page.

  5. In the filter box, type CurrentTenantQuery.

    If CurrentTenantQuery doesn’t appear, refresh the page again while the Network tab is open.

    Tip

  6. Click a CurrentTenantQuery request, then click the Response tab.

  7. Copy the value of the uuid field. This string is your workspace UUID.

Get an Access Token 

All calls to the Agentforce Operations REST API require a token. Create a token by using the client ID, the client secret, and your workspace UUID. An access token expires after 2 hours.

  1. Send a POST request to the token endpoint with your service account credentials and workspace UUID. In the code sample, replace <your-workspace-uuid>, <your-client-id>, <your-client-secret>, and <your-instance> with the values for your workspace.

    Get an Access Token
    1curl -X POST \
2  -H 'Content-Type: application/x-www-form-urlencoded' \
3  --data-urlencode 'grant_type=client_credentials' \
4  --data-urlencode 'client_id=<your-client-id>' \
5  --data-urlencode 'client_secret=<your-client-secret>' \
6  https://<your-instance>.regrello.salesforce.com/oauth/<your-workspace-uuid>/token

  2. Verify your response. A successful response looks like this:

    Sample Token Response
    1{
2  "access_token": "eyJ...(shortened)",
3  "expires_in": 7200,
4  "token_type": "Bearer"
5}

  3. Copy the access_token value to use in your API calls.

    Tokens expire after 2 hours.

    Note

Call the API 

With your access token and workspace UUID, you’re ready to call the API.

  1. Call an API endpoint. Every request requires two headers: Authorization and X-Regrello-Workspace-ID. This example retrieves a list of published blueprints in your workspace. In the code sample, replace <your-instance>, <your-access-token>, and <your-workspace-uuid> with the values for your workspace.

    Get Blueprints List
    1curl 'https://<your-instance>.regrello.salesforce.com/api/v1/blueprints' \
2  -H "Authorization: Bearer <your-access-token>" \
3  -H "X-Regrello-Workspace-ID: <your-workspace-uuid>"

  2. Verify the response. A successful response returns HTTP 200. In the get blueprints list example, the response body looks like this:

    Sample Response
    1[
2   {
3   "blueprintUuid": "ckuJA2XGT-Q",
4   "description": null,
5   "id": 2227,
6   "name": "API Example",
7   "numberOfStages": 1,
8   "type": "COMPANY",
9   "versionNumber": 1
10   }
11]

    Pagination details are in the SFDC-Pagination-Offset, SFDC-Pagination-Limit, SFDC-Pagination-Total-Count, and SFDC-Pagination-Result-Count response headers.

    Note

See Also 

Get Started