Clarifeye Service Accounts API
The Service Accounts API from Clarifeye — 5 operation(s) for service accounts.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/clarifeye:clarifeye-service-accounts-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Clarifeye Platform API — Full API Documentation Service…
description: 'Complete REST API reference for the Clarifeye Platform.
Documents every endpoint exposed by the platform — the public surface plus
the advanced surface: pipeline customization (extraction flows, pipeline
runs, warehouse tables, document tag/metadata configuration), the pre-MCP
AI surface (agent settings, playground conversations, conversation-scoped
feedback views, notifications), and the impersonation header. New AI
integrations should consume knowledge via MCP rather than the
conversation/agent-settings endpoints documented here.
## Authentication
All endpoints require authentication. Include the Authorization header in every request using either format:
- `Authorization: Token `
- `Authorization: Bearer `
## Service accounts and API keys
Integrations authenticate with an **API key** of a **service account**:
- `Authorization: Bearer ` (keys start with `cfk_`)
A service account is an ordinary member (role `member`) of one organization that cannot log
in. Organization admins create it and mint its keys on the organization''s *Service
accounts* page (`/organizations/{id}/service-accounts/`, `/organization-api-keys/`), and
give it access to knowledge stores with ordinary store permissions. A key is valid on every
endpoint and acts as its service account: it reaches exactly the stores, with exactly the
rights, the account was given. An account can hold several keys (each with its own name,
optional expiry and revocation), so a key can be rotated without changing identity.
A refused key answers **403** with one of: `Invalid API key.`, `API key revoked.`,
`API key expired.`, `API key disabled.` (the service account is disabled).
Any valid key may also call `POST /organizations/{id}/provision-user/` and
`POST /organizations/{id}/deprovision-user/` for its own organization (the `{id}` in the
path must be the key''s organization). The email domains these may pre-create accounts for
are configured by Clarifeye on the organization (`allowed_provisioning_domains`).
## Impersonation
Certain endpoints support user impersonation for creating or listing data on behalf of other users.
This is useful for integrating external systems that need to attribute actions to specific users.
**Header:** `X-Impersonate-Email`
**Required Permission:** `CAN_IMPERSONATE_OTHER_USERS` (for a person, contact Clarifeye to enable it; org admins grant it to a service account on the organization''s Service accounts page)
**Behavior:**
- If the header is provided and the impersonator has the required permission, the action is performed as the target user
- If the target user is not found, the request proceeds as the original authenticated user
- If the target user does not have access to the project, the request proceeds as the original authenticated user
- If the impersonator lacks the `CAN_IMPERSONATE_OTHER_USERS` permission, the header is ignored
**With an API key** the request fails instead (**403**) whenever impersonation cannot
happen: missing permission, unknown target, target without access to the store, target that
is itself a service account, or an endpoint outside a store. A key never silently acts as
its own service account when impersonation was asked for.'
version: 1.0.0
contact:
name: Clarifeye Support
servers:
- url: https://eu.app.clarifeye.ai/api/v1
description: EU
- url: https://us.app.clarifeye.ai/api/v1
description: US
security:
- BearerAuth: []
- TokenAuth: []
tags:
- name: Service Accounts
paths:
/organizations/{id}/service-accounts/:
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
get:
operationId: listServiceAccounts
tags:
- Service Accounts
summary: List the organization's service accounts (org admin)
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: Service accounts, ordered by name.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/ServiceAccount'
'403':
description: Caller is not an admin of the organization.
post:
operationId: createServiceAccount
tags:
- Service Accounts
summary: Create a service account (org admin)
description: 'Creates a member (role `member`) of the organization that cannot log in and never
receives emails. It has no store access until one is added with
`POST .../service-accounts/{user_id}/stores/`, and no key until one is minted with
`POST /organization-api-keys/`.'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
maxLength: 255
description: Unique in the organization (case-insensitive).
responses:
'201':
description: Created.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceAccount'
'400':
description: Missing name, or the name is already used in this organization.
'403':
description: Caller is not an admin of the organization.
/organizations/{id}/service-accounts/{user_id}/:
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: user_id
in: path
required: true
schema:
type: string
format: uuid
get:
operationId: getServiceAccount
tags:
- Service Accounts
summary: Service account detail, with its stores and keys (org admin)
responses:
'200':
description: Service account.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ServiceAccount'
- type: object
properties:
stores:
type: array
items:
$ref: '#/components/schemas/ServiceAccountStore'
keys:
type: array
items:
$ref: '#/components/schemas/OrganizationApiKey'
'403':
description: Caller is not an admin of the organization.
'404':
description: No such service account in this organization.
patch:
operationId: updateServiceAccount
tags:
- Service Accounts
summary: Rename, disable / re-enable, or set the usage limit (org admin)
description: '`is_active: false` disables the account: every one of its keys answers 403
`API key disabled.` until it is re-enabled. Its data and store access are kept.
Service accounts cannot be deleted.'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
is_active:
type: boolean
user_usage_limit_mode:
type: string
enum:
- inherit
- unlimited
- custom
user_usage_alert_ccu:
type:
- number
- 'null'
user_usage_block_ccu:
type:
- number
- 'null'
responses:
'200':
description: Updated.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceAccount'
'400':
description: Duplicate name or invalid usage limit.
'403':
description: Caller is not an admin of the organization.
/organizations/{id}/service-accounts/{user_id}/stores/:
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: user_id
in: path
required: true
schema:
type: string
format: uuid
get:
operationId: listServiceAccountStores
tags:
- Service Accounts
summary: The knowledge stores of the organization the account can access (org admin)
responses:
'200':
description: Store access rows.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ServiceAccountStore'
post:
operationId: addServiceAccountStore
tags:
- Service Accounts
summary: Give the account access to a store of the organization (org admin)
description: 'Creates the account''s store permission row. `CAN_IMPERSONATE_OTHER_USERS` may be granted
here (and only here, for a service account); `CAN_TAKE_INTERVIEW` is refused.'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- project
- permissions
properties:
project:
type: string
format: uuid
permissions:
type: array
minItems: 1
items:
type: string
enum:
- CAN_PERFORM_ADMIN_ACTIONS
- CAN_VIEW_DATA
- CAN_IMPERSONATE_OTHER_USERS
profile:
type: string
enum:
- tech
- contributor
- user
default: tech
responses:
'201':
description: Access granted.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceAccountStore'
'400':
description: Store of another organization, already granted, or invalid permissions.
'403':
description: Caller is not an admin of the organization.
/organizations/{id}/service-accounts/{user_id}/stores/{project_id}/:
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: user_id
in: path
required: true
schema:
type: string
format: uuid
- name: project_id
in: path
required: true
schema:
type: string
format: uuid
patch:
operationId: updateServiceAccountStore
tags:
- Service Accounts
summary: Change the account's permissions on a store (org admin)
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
permissions:
type: array
minItems: 1
items:
type: string
enum:
- CAN_PERFORM_ADMIN_ACTIONS
- CAN_VIEW_DATA
- CAN_IMPERSONATE_OTHER_USERS
profile:
type: string
enum:
- tech
- contributor
- user
responses:
'200':
description: Updated.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceAccountStore'
'404':
description: The account has no access to this store.
delete:
operationId: removeServiceAccountStore
tags:
- Service Accounts
summary: Remove the account's access to a store (org admin)
responses:
'204':
description: Removed.
'404':
description: The account has no access to this store.
/projects/{project_id}/service-accounts/:
get:
operationId: listProjectServiceAccounts
tags:
- Service Accounts
summary: Service accounts with access to this store (read-only)
description: 'Same access rule as the store''s member list. Service accounts are not listed by
`/projects/{project_id}/users/` and are managed on the organization''s Service accounts
page only.'
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/ProjectServiceAccount'
components:
parameters:
ProjectId:
name: project_id
in: path
required: true
description: UUID of the project
schema:
type: string
format: uuid
Offset:
name: offset
in: query
description: Number of results to skip for pagination
schema:
type: integer
default: 0
minimum: 0
Limit:
name: limit
in: query
description: Maximum number of results per page
schema:
type: integer
default: 100
minimum: 1
maximum: 1000
schemas:
PaginatedResponse:
type: object
properties:
count:
type: integer
description: Total number of results
next:
type:
- string
- 'null'
format: uri
description: URL to next page of results
previous:
type:
- string
- 'null'
format: uri
description: URL to previous page of results
results:
type: array
items: {}
ProjectServiceAccount:
type: object
properties:
id:
type: string
format: uuid
user_id:
type: string
format: uuid
name:
type: string
is_active:
type: boolean
permissions:
type: array
items:
type: string
profile:
type: string
enum:
- tech
- contributor
- user
ServiceAccount:
type: object
properties:
id:
type: string
format: uuid
description: The service account's user id.
name:
type: string
is_active:
type: boolean
stores_count:
type: integer
description: Stores of this organization the account can access.
keys_count:
type: integer
description: Active (not revoked, not expired) keys.
last_used_at:
type:
- string
- 'null'
format: date-time
created_at:
type: string
format: date-time
user_usage_limit_mode:
type: string
enum:
- inherit
- unlimited
- custom
user_usage_alert_ccu:
type:
- number
- 'null'
user_usage_block_ccu:
type:
- number
- 'null'
effective_alert_ccu:
type:
- number
- 'null'
effective_block_ccu:
type:
- number
- 'null'
period_ccu:
type:
- number
- 'null'
alerted_this_period:
type: boolean
blocked:
type: boolean
ServiceAccountStore:
type: object
properties:
id:
type: string
format: uuid
project:
type: string
format: uuid
project_name:
type: string
permissions:
type: array
items:
type: string
profile:
type: string
enum:
- tech
- contributor
- user
OrganizationApiKey:
type: object
description: API key metadata. Never includes the secret or its stored forms.
properties:
id:
type: string
format: uuid
organization:
type: string
format: uuid
service_account:
type: object
properties:
id:
type: string
format: uuid
display_name:
type: string
name:
type: string
key_prefix:
type: string
description: The 8 characters after `cfk_`, to recognise a key without revealing it.
status:
type: string
enum:
- active
- expired
- revoked
created_at:
type: string
format: date-time
created_by:
type:
- object
- 'null'
properties:
id:
type: string
format: uuid
email:
type: string
display_name:
type:
- string
- 'null'
expires_at:
type:
- string
- 'null'
format: date-time
revoked_at:
type:
- string
- 'null'
format: date-time
last_used_at:
type:
- string
- 'null'
format: date-time
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'Use `Authorization: Bearer <token>`. The token is either a user token / OAuth access
token, or a service-account API key (`cfk_...`). A key is valid on every endpoint and
acts as its service account, an organization member with per-store permissions.
Refused keys answer 403 with `Invalid API key.`, `API key revoked.`,
`API key expired.` or `API key disabled.`.
'
TokenAuth:
type: apiKey
in: header
name: Authorization
description: 'Use Authorization: Token <token>'
x-tagGroups:
- name: Extractors
tags:
- Object Extractors
- Tag Extractors
- Chunks Extractors
- Parsing Extractors
- Document Filter Extractors
- Chunk Tag Filter Extractors
- Document Tag Extractors
- Tag Alerts Extractors
- Object Alerts Extractors
- Imported Object Extractors
x-provenance:
method: harvested
publisher: Clarifeye
source: https://docs.clarifeye.ai/api-reference/openapi-full.yaml
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)