API Tokens

Endpoints for managing API tokens for programmatic access.

GET /api/tokens

List API tokens with optional filtering.

Authentication: Required

Query Parameters:

Parameter	Type	Description
reportId	string	Filter by report ID
datasourceId	string	Filter by datasource ID
assistantId	string	Filter by assistant ID
visualId	string	Filter by visual ID
datasetId	string	Filter by dataset ID
queryId	string	Filter by query ID
username	string	Filter by username

Response:

{
  "_links": {
    "self": { "href": "/api/tokens" }
  },
  "_embedded": {
    "inf:token": [
      {
        "id": "abc123-token-id",
        "username": "admin",
        "type": "personal",
        "notes": "API integration token",
        "token": "i5t_abc123...",
        "readOnly": false,
        "restrict": "cidr",
        "cidr": "192.168.1.0/24",
        "reportId": null,
        "datasourceId": null,
        "assistantId": "assistant-123",
        "createdAt": "2024-01-15T10:00:00Z",
        "data": {
          "customField": "value"
        },
        "_links": {
          "self": { "href": "/api/tokens/abc123-token-id" }
        }
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 1
}

---

POST /api/tokens

Create a new API token.

Authentication: Required

Permission: tokens:create

Request Body:

Field	Type	Required	Description
type	string	Yes	Token type (e.g., personal, assistant)
notes	string	No	Token description or notes
readOnly	boolean	No	Restrict to read-only operations (default: false)
restrict	string	No	Restriction type: host or cidr
host	string	No	Allowed hostname (if restrict: 'host')
cidr	string	No	CIDR range (if restrict: 'cidr')
reportId	string	No	Associated report ID
datasourceId	string	No	Associated datasource ID
assistantId	string	No	Associated assistant ID
visualId	string	No	Associated visual ID
datasetId	string	No	Associated dataset ID
queryId	string	No	Associated query ID
data	object	No	Custom metadata object

Example Request:

{
  "type": "personal",
  "notes": "Production API integration",
  "readOnly": false,
  "restrict": "cidr",
  "cidr": "10.0.0.0/8",
  "assistantId": "assistant-123"
}

Response:

{
  "id": "new-token-id",
  "username": "admin",
  "type": "personal",
  "notes": "Production API integration",
  "token": "i5t_newly_generated_token_value",
  "readOnly": false,
  "restrict": "cidr",
  "cidr": "10.0.0.0/8",
  "assistantId": "assistant-123",
  "createdAt": "2024-02-09T10:00:00Z",
  "_links": {
    "self": { "href": "/api/tokens/new-token-id" }
  }
}

Status: 201 Created

Location Header: Set to the new token's URL

Token Security

The token value is only returned once upon creation. Store it securely - it cannot be retrieved later.

---

GET /api/tokens/{id}

Retrieve a specific API token.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Token UUID

Response:

{
  "id": "abc123-token-id",
  "username": "admin",
  "type": "personal",
  "notes": "API integration token",
  "readOnly": false,
  "restrict": "host",
  "host": "api.example.com",
  "createdAt": "2024-01-15T10:00:00Z",
  "data": {},
  "_links": {
    "self": { "href": "/api/tokens/abc123-token-id" }
  }
}

Token Value Not Included

The actual token value is NOT returned in GET requests. It is only provided upon creation.

---

PUT /api/tokens/{id}

Update an API token's metadata.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Token UUID (required)

Request Body:

Field	Type	Description
notes	string	Update token notes/description
data	object	Update custom metadata
readOnly	boolean	Change read-only status
restrict	string	Update restriction type: host, cidr, or null
host	string	Update allowed hostname
cidr	string	Update CIDR range

Example Request:

{
  "notes": "Updated notes",
  "readOnly": true,
  "restrict": "host",
  "host": "secure.example.com"
}

Response:

Returns the updated token object.

---

DELETE /api/tokens/{id}

Revoke an API token.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Token UUID

Response:

204 No Content

Permanent Revocation

Deleting a token immediately revokes access. This cannot be undone. Any requests using the token will fail with 401 Unauthorized.

---

GET /api/token-types

List available token types and their templates.

Authentication: Required

Response:

{
  "_links": {
    "self": { "href": "/api/token-types" }
  },
  "_embedded": {
    "inf:token-type": [
      {
        "id": "personal",
        "name": "Personal Access Token",
        "description": "General purpose API token"
      },
      {
        "id": "assistant",
        "name": "Assistant Token",
        "description": "Token for assistant API access"
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 2
}

---

GET /api/token-types/{id}

Get details for a specific token type.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Token type ID

Response:

{
  "id": "personal",
  "name": "Personal Access Token",
  "description": "General purpose API token",
  "fields": [
    {
      "name": "notes",
      "type": "string",
      "required": false
    }
  ]
}

---

GET /api/token-templates

Get token templates for UI generation.

Authentication: Required

Response:

Array of token template objects with field definitions.