Clarifymedical API Keys API

openapi: 3.2.0
info:
  title: Clarify API Keys API
  description: The Clarify API OpenAPI documentation
  version: '0.1'
  contact: {}
servers:
- url: https://api.clarify.ai/v1
security:
- apiKey: []
- bearer: []
tags:
- name: API Keys
paths:
  /workspaces/{workspace}/api-keys:
    get:
      description: Returns API keys as a JSON:API list with `links` and `meta`, in one page. Requires a user access token. Admins see every personal and workspace key, and members see only their own personal keys. Secrets are never returned.
      operationId: getApiKeys
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      responses:
        '200':
          description: The API keys visible to the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOfApiKeysResponseDto'
              example:
                links:
                  next: null
                  prev: null
                meta:
                  total_records: 1
                  total_pages: 1
                  offset: 0
                  limit: 500
                data:
                - type: api-key
                  id: 4a7c2e9f-6b1d-4e3a-8f5c-0d2b4e6a8c19
                  attributes:
                    _id: 4a7c2e9f-6b1d-4e3a-8f5c-0d2b4e6a8c19
                    name: Acme CRM sync
                    key_prefix: 3f9a1c7e
                    scopes: []
                    actor:
                      type: user
                      id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    on_behalf_of: null
                    hidden: false
                    _created_by: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    expires_at: null
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _updated_at: '2026-02-01T17:45:00.000Z'
                    last_used_at: '2026-02-01T17:45:00.000Z'
        '401':
          description: The request did not send a bearer access token.
      security:
      - bearer: []
      summary: List API keys
      tags:
      - API Keys
    post:
      description: Creates an API key and returns it as a JSON:API resource whose `cleartext_api_key` holds the secret, shown only this once. Requires a user access token, because an API key cannot create another API key. Only admins can create `workspace` keys.
      operationId: createApiKey
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeysRequestDto'
            examples:
              personal:
                summary: Create a personal API key
                value:
                  data:
                    type: api-key
                    attributes:
                      name: Acme CRM sync
                      scopes: []
                      actor_type: user
      responses:
        '201':
          description: The created API key, including its secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeysResponseDto'
              example:
                data:
                  type: api-key
                  id: 4a7c2e9f-6b1d-4e3a-8f5c-0d2b4e6a8c19
                  attributes:
                    _id: 4a7c2e9f-6b1d-4e3a-8f5c-0d2b4e6a8c19
                    name: Acme CRM sync
                    key_prefix: 3f9a1c7e
                    scopes: []
                    actor:
                      type: user
                      id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    on_behalf_of: null
                    hidden: false
                    _created_by: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    expires_at: null
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _updated_at: '2026-01-15T09:30:00.000Z'
                    last_used_at: null
                    cleartext_api_key: example00000000000000000000000000
        '401':
          description: The request did not send a bearer access token.
        '403':
          description: A non-admin asked for a `workspace` key.
      security:
      - bearer: []
      summary: Create an API key
      tags:
      - API Keys
  /workspaces/{workspace}/api-keys/{id}:
    delete:
      description: Revokes an API key so it stops authenticating requests. Requires a user access token. Admins can delete any key, and members only their own personal keys.
      operationId: deleteApiKey
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The unique ID of the API key.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      responses:
        '204':
          description: The API key was deleted.
        '401':
          description: The request did not send a bearer access token.
        '404':
          description: The API key does not exist or is not yours to delete.
      security:
      - bearer: []
      summary: Delete an API key
      tags:
      - API Keys
components:
  schemas:
    CreateApiKeysResponseDto:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum:
              - api-key
              description: The resource type; matches the `object` path parameter.
            id:
              type: string
              description: The unique ID of the resource.
            attributes:
              type: object
              properties:
                _id:
                  type: string
                  description: The unique ID of the API key.
                name:
                  type: string
                  description: The display name of the API key.
                key_prefix:
                  type: string
                  description: The first characters of the key, shown to identify it.
                scopes:
                  type: array
                  items:
                    type: string
                  description: The access scopes recorded on the key, such as `manage:entities`.
                actor:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                      - workspace
                      - user
                      - rep
                      - agent
                      - workflow
                      description: 'The kind of identity: `user`, `workspace`, `rep`, `agent`, or `workflow`.'
                    id:
                      type: string
                      description: The unique ID of the identity.
                  required:
                  - type
                  - id
                  description: The identity the API key authenticates as.
                on_behalf_of:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                      - user
                      description: Always `user`.
                    id:
                      type: string
                      description: The unique ID of the user.
                  required:
                  - type
                  - id
                  nullable: true
                  description: The user an agent or workflow key acts for, or `null` for keys that act as themselves.
                hidden:
                  type: boolean
                  description: True for server-managed keys that listings omit.
                _created_by:
                  type: string
                  nullable: true
                  description: The ID of the user who created the key, or `null` for server-created keys.
                expires_at:
                  type: string
                  format: date-time
                  nullable: true
                  description: The time the key stops working, or `null` when it never expires.
                _created_at:
                  type: string
                  format: date-time
                  description: The time the key was created.
                _updated_at:
                  type: string
                  format: date-time
                  description: The time the key was last updated.
                last_used_at:
                  type: string
                  format: date-time
                  nullable: true
                  description: The time the key last authenticated a request, or `null` if never.
                cleartext_api_key:
                  type: string
                  description: The full secret key. It is returned only once, at creation, so store it now.
              required:
              - _id
              - name
              - key_prefix
              - scopes
              - actor
              - on_behalf_of
              - hidden
              - _created_by
              - expires_at
              - _created_at
              - _updated_at
              - last_used_at
              - cleartext_api_key
              description: Field values keyed by field name; available fields depend on the object’s schema.
            relationships:
              type: object
              properties: {}
              description: Related resources keyed by relationship name, present when requested via `include`.
          required:
          - type
          - id
          - attributes
          description: The resource.
      required:
      - data
    CreateApiKeysRequestDto:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum:
              - api-key
              description: The resource type, always `api-key`.
            attributes:
              description: Field values keyed by field name; available fields depend on the object’s schema. System fields (prefixed with a single `_`) cannot be set.
              type: object
              properties:
                name:
                  type: string
                  description: The display name of the API key.
                scopes:
                  default: []
                  type: array
                  items:
                    type: string
                  description: The access scopes to record on the key, such as `manage:entities`. Defaults to an empty list.
                actor_type:
                  type: string
                  enum:
                  - workspace
                  - user
                  description: 'Who the key acts as: `user` for a personal key bound to you, or `workspace` for an admin-only key not tied to a person. Defaults to `user`.'
              required:
              - name
              additionalProperties: true
          required:
          - type
          - attributes
          additionalProperties: false
          description: The resource to create.
      required:
      - data
    ListOfApiKeysResponseDto:
      type: object
      properties:
        links:
          type: object
          properties:
            next:
              type: string
              nullable: true
              description: URL of the next page, or `null` on the last page.
            prev:
              type: string
              nullable: true
              description: URL of the previous page, or `null` on the first page.
          required:
          - next
          - prev
          description: Pagination links.
        meta:
          type: object
          properties:
            total_records:
              type: number
              description: Total number of records across all pages.
            total_pages:
              type: number
              description: Total number of pages at the current page size.
          required:
          - total_records
          - total_pages
          description: Pagination metadata.
        data:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - api-key
                description: The resource type; matches the `object` path parameter.
              id:
                type: string
                description: The unique ID of the resource.
              attributes:
                type: object
                properties:
                  _id:
                    type: string
                    description: The unique ID of the API key.
                  name:
                    type: string
                    description: The display name of the API key.
                  key_prefix:
                    type: string
                    description: The first characters of the key, shown to identify it.
                  scopes:
                    type: array
                    items:
                      type: string
                    description: The access scopes recorded on the key, such as `manage:entities`.
                  actor:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                        - workspace
                        - user
                        - rep
                        - agent
                        - workflow
                        description: 'The kind of identity: `user`, `workspace`, `rep`, `agent`, or `workflow`.'
                      id:
                        type: string
                        description: The unique ID of the identity.
                    required:
                    - type
                    - id
                    description: The identity the API key authenticates as.
                  on_behalf_of:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                        - user
                        description: Always `user`.
                      id:
                        type: string
                        description: The unique ID of the user.
                    required:
                    - type
                    - id
                    nullable: true
                    description: The user an agent or workflow key acts for, or `null` for keys that act as themselves.
                  hidden:
                    type: boolean
                    description: True for server-managed keys that listings omit.
                  _created_by:
                    type: string
                    nullable: true
                    description: The ID of the user who created the key, or `null` for server-created keys.
                  expires_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: The time the key stops working, or `null` when it never expires.
                  _created_at:
                    type: string
                    format: date-time
                    description: The time the key was created.
                  _updated_at:
                    type: string
                    format: date-time
                    description: The time the key was last updated.
                  last_used_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: The time the key last authenticated a request, or `null` if never.
                required:
                - _id
                - name
                - key_prefix
                - scopes
                - actor
                - on_behalf_of
                - hidden
                - _created_by
                - expires_at
                - _created_at
                - _updated_at
                - last_used_at
                description: Field values keyed by field name; available fields depend on the object’s schema.
              relationships:
                type: object
                properties: {}
                description: Related resources keyed by relationship name, present when requested via `include`.
            required:
            - type
            - id
            - attributes
          description: The page of resources.
      required:
      - links
      - meta
      - data
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key authentication. Send your key in the Authorization header as: `api-key <your-api-key>`.'
    bearer:
      type: http
      scheme: bearer
      description: 'User access token authentication. Every endpoint accepts it, and endpoints that act as a person accept only it. Send a WorkOS access token in the Authorization header as: `Bearer <token>`.'