REST API Access

Synopsis

Exposes DataStream's management operations over a versioned REST API, so resources can be created and managed programmatically instead of through the dashboard. Every request authenticates with an API token that you create and govern from the web interface.

The feature has two surfaces:

• API Tokens — a tab under Organization > Settings where you generate, manage, regenerate, and delete the tokens that authenticate API requests. Covered in the sections below.
• API Preview — a drawer available on the Create screens of most resources. It renders a ready-to-run curl command (PowerShell or Bash) equivalent to the form you are filling in, so you can copy the exact request the dashboard would send. See API Preview.

The API is served under the base path /api/v1. The full, interactive endpoint reference is published as a Swagger document — see API Reference.

Authentication

Every API request authenticates with a bearer token in the Authorization header:

Authorization: Bearer <api-token>

A token carries the permissions of the single role assigned to it when it was created. The API enforces that role on every request: an operation succeeds only if the token's role grants the required permission, and returns 401 Unauthorized when the token is missing, unrecognized, or expired.

To obtain a token, generate one from the API Tokens tab. The full token value is shown only once, at creation time; afterward only a masked form is available.

warning

Treat API tokens as secrets. Anyone holding a token can call the API with that token's role permissions until the token expires or is deleted. Store tokens in a secure location and regenerate them if you suspect exposure.

API Tokens

An API token is a credential that authenticates REST API requests. Each token has a name, an optional description, an assigned role that determines its permissions, and an optional time limit after which it stops working.

Accessing API Tokens

To open the API token management interface:

1. Click the hamburger menu in the top left corner.
2. Select Organization > Settings.
3. Open the API Tokens tab.

API Tokens Table

The table lists every API token in the current organization:

• Token Name — Human-readable identifier. Click to open the token detail drawer.
• Description — Optional free-text note.
• Token — The masked token value. Tokens are hidden by default; clicking the show icon reveals the token value.
• Time Limit — The expiration date, or Indefinite when no time limit is set.
• Status — Active or Expired. A token with a time limit moves to Expired automatically once that time is reached.

Controls

Above the table, the Search field filters tokens by name, and the Generate New Token button opens the creation wizard. Pagination controls at the bottom navigate between pages.

Actions Menu

On the right side of each row, the actions menu provides:

• Manage API token — Opens the token detail page.
• Delete API token — Prompts for confirmation; see Regenerate and Delete.

Create an API Token

Click Generate New Token to open the four-step wizard.

Step 1 — Token Settings

• Token name — Required. Between 3 and 128 characters.
• Description — Optional free-text note (up to 500 characters).

Step 2 — Token Configuration

• API Key expiration — Optional. Leave Set expiration unchecked to create a token that never expires. When checked, the checkbox label changes to Set API token time limit and an API token expiration field appears — choose a preset (8 hours, 24 hours, 1 week, 1 month) or a custom date and time. After the expiration date, the token is disabled.
• Assign role — Required. Select one role from the existing custom roles or the pre-defined API roles. The token inherits this role's permissions.

note

The Owner role cannot be assigned to an API token.

Step 3 — Review and Create

Review the summary of Steps 1 and 2 — Token Name, Description, Token Time Limit, and Assign Role. Use Back to return to an earlier step, or click Create token to generate the token.

Step 4 — Save Token

The token is created and displayed. Use the reveal icon to show the value, the copy control to copy it, or Download token to save it to a file.

warning

The full token value is shown only on this step. You will not be able to see or retrieve it again later. Copy or download it before leaving the page.

API Token Details

Click a token's Token Name in the table, then Manage API Token in the drawer, to open the detail page. It has three tabs.

General Overview

• Name and Description — Editable. Click Manage token details to modify.
• An information panel shows the read-only Created and Last updated timestamps.

Token Configuration

• Token Time Limit — Read-only. The expiration set at creation cannot be changed from this page.
• Assigned Role — Editable. Click Manage token configuration to assign a different role.
• Regenerate API token — Invalidates the current token value and issues a new one. The link appears only after clicking Manage token configuration to enter edit mode; see Regenerate and Delete.

Activity Logs

An audit trail of actions performed on this token, with the columns Date, User, User IP, Object Type, Object, Action, and Action Description. A Search field and a Timeframe filter (Last 24 hours, Last 7 days, Last 30 days, Last 90 days, All time) narrow the list. This is the same audit model used across the platform — see Audit Logs.

Regenerate and Delete

Regenerate — On the Token Configuration tab, click Manage token configuration to enter edit mode, then click Regenerate API token. A confirmation modal appears. On confirmation, the existing token value is permanently invalidated and a new value is issued, shown only once with the same copy and download options as creation. Any application using the old value loses access until it is updated with the new token.

Delete — Select Delete API token from the table row actions, or Delete token from the detail page actions, and confirm. Deletion is permanent, and any service still using the token immediately loses access.

warning

Both Regenerate and Delete break any integration currently using the token. Update every application that relies on a token before regenerating or deleting it.

API Preview

The API Preview drawer shows the REST API request equivalent to a resource you are creating in the dashboard. It appears on the Review step of the Create flow for the following resources:

• Directors and Clusters
• Devices and Agent enrollment templates
• Targets
• Datasets and Profiles
• Advanced Routes
• Pipelines
• Vault secrets and provider configurations

On the review step, click Show API Preview to open the drawer. It displays:

• The HTTP method and endpoint path for the resource (for example, POST /devices).
• A PowerShell tab and a Bash tab, each containing a copyable command that reproduces the request, populated with the values from the form.
• A View API tokens button that opens the API Tokens tab, and a View API docs button that opens the Swagger reference.

The commands reference two variables you supply: $BASE_URL (your API base, ending in /api/v1) and $API_TOKEN (a token from the API Tokens tab). For example, the Bash command to create a device:

curl -X POST "$BASE_URL/devices" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-device"
  }'

The equivalent PowerShell command:

$headers = @{
  "Authorization" = "Bearer $API_TOKEN"
}

$body = @'
{
  "name": "my-device"
}
'@

Invoke-RestMethod -Method POST -Uri "$BASE_URL/devices" `
  -Headers $headers `
  -ContentType "application/json" `
  -Body $body

The request runs only if the supplied token's role grants the permission the endpoint requires.

API Reference

The complete endpoint reference is published as an interactive Swagger document at /api/v1/swagger/index.html on your DataStream host. It lists every available resource, request and response schema, and the permissions each endpoint requires. The View API docs button in the API Preview drawer links directly to it.