API Key Service

The API Key Service provides methods for creating, managing, and revoking API keys for programmatic access to the BSH Engine API.

Methods

create

Creates a new API key for programmatic access. Returns the full API key value (only shown once).

Personal API Key


await bshEngine.apiKeys.create({
  payload: {
    name: 'My Personal API Key',
    type: 'PERSONAL',
    duration: 30,
    description: 'API key for personal scripts'
  }
});

Property	Type	Required	Description
`name`	string	yes	A descriptive name for the API key
`type`	`PERSONAL`, `MACHINE`	no	The type of API key (default: `PERSONAL`)
`duration`	number	yes	Expiration period in days (must be greater than 0)
`description`	string	no	Additional notes about the key’s purpose
`scopes`	string[]	yes (for `MACHINE`)	Entity and action permissions in format `EntityName:ACTION` (e.g., `BshUsers:read`, `BshEntities:*`)

details

Retrieves detailed information about an API key by its ID.


await bshEngine.apiKeys.details({
  id: 123
});

Property	Type	Required	Description
`id`	number	yes	The unique identifier of the API key

revoke

Immediately invalidates an API key, preventing any further use.


await bshEngine.apiKeys.revoke({
  id: 123
});

Property	Type	Required	Description
`id`	number	yes	The unique identifier of the API key to revoke

getById

Retrieves an API key by its ID.


await bshEngine.apiKeys.getById({
  id: 123
});

Property	Type	Required	Description
`id`	number	yes	The unique identifier of the API key to retrieve

search

Searches for API keys using the BSH Search object. Supports filtering, sorting, pagination, and grouping.


await bshEngine.apiKeys.search({
  payload: {
    fields: ['id', 'name', 'type', 'status'],
    filters: [
      {
        field: 'type',
        operator: 'eq',
        value: 'MACHINE'
      }
    ],
    sort: [
      {
        field: 'createdAt',
        direction: -1
      }
    ],
    pagination: {
      page: 0,
      size: 10
    }
  }
});

Property	Type	Required	Description
`payload`	BshSearch	yes	The search criteria. See BSH Search documentation for details

list

Lists API keys with optional query parameters for pagination, sorting, and filtering.


await bshEngine.apiKeys.list({
  queryParams: {
    page: '0',
    size: '10',
    sort: 'createdAt:desc',
    filter: 'type:eq:MACHINE'
  }
});

Property	Type	Required	Description
`queryParams`	object	no	Query parameters for listing API keys
`queryParams.page`	string	no	The page number (default: 0)
`queryParams.size`	string	no	The number of items per page (default: 10)
`queryParams.sort`	string	no	Sort by field and direction (format: `field:direction`)
`queryParams.filter`	string	no	Filter conditions (format: `field:operator:value`, comma-separated for multiple filters)

count


// Count all user's API keys
await bshEngine.apiKeys.count({});
 
// Count filtered user's API keys
await bshEngine.apiKeys.count({
  payload: {
    filters: [
      {
        field: 'name',
        operator: 'eq',
        value: 'ApiKey 1'
      }
    ]
  }
});

deleteById

Deletes an API key by its ID.


await bshEngine.apiKeys.deleteById({
  id: 123
});

Property	Type	Required	Description
`id`	number	yes	The unique identifier of the API key to delete