# User Agents

## List

`client.zones.userAgents.list(stringzoneID, UserAgentListParamsquery?, RequestOptionsoptions?): UserAgentListResponse`

**get** `/zones/{zoneId}/user-agents`

Returns a list of user agents in the specified zone. User agents represent client software (browsers, desktop apps, CLI tools) registered via OAuth 2.0 Dynamic Client Registration.

### Parameters

- `zoneID: string`

- `query: UserAgentListParams`

  - `after?: string`

    Cursor for forward pagination

  - `before?: string`

    Cursor for backward pagination

  - `expand?: "total_count" | Array<"total_count">`

    - `"total_count"`

      - `"total_count"`

    - `Array<"total_count">`

      - `"total_count"`

  - `limit?: number`

    Maximum number of items to return

### Returns

- `UserAgentListResponse`

  - `items: Array<UserAgent>`

    - `id: string`

      Unique identifier of the user agent

    - `created_at: string`

      Entity creation timestamp

    - `identifier: string`

      User agent identifier (serves as OAuth client_id). Format: ua:{sha256_hash}

    - `name: string`

      Human-readable name

    - `organization_id: string`

      Organization that owns this user agent

    - `slug: string`

      URL-safe identifier, unique within the zone

    - `updated_at: string`

      Entity update timestamp

    - `zone_id: string`

      Zone this user agent belongs to

  - `pagination: Pagination`

    Cursor-based pagination metadata

    - `after_cursor: string | null`

      An opaque cursor used for paginating through a list of results

    - `before_cursor: string | null`

      An opaque cursor used for paginating through a list of results

    - `total_count?: number`

      Total number of items matching the query. Only included when expand[]=total_count is requested.

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const userAgents = await client.zones.userAgents.list('zoneId');

console.log(userAgents.items);
```

## Retrieve

`client.zones.userAgents.retrieve(stringid, UserAgentRetrieveParamsparams, RequestOptionsoptions?): UserAgent`

**get** `/zones/{zoneId}/user-agents/{id}`

Returns details of a specific user agent by user agent ID

### Parameters

- `id: string`

- `params: UserAgentRetrieveParams`

  - `zoneId: string`

    Zone ID

### Returns

- `UserAgent`

  A User Agent represents a user agent (browser, desktop app, CLI tool) that can initiate user sessions via OAuth 2.0 Dynamic Client Registration.

  - `id: string`

    Unique identifier of the user agent

  - `created_at: string`

    Entity creation timestamp

  - `identifier: string`

    User agent identifier (serves as OAuth client_id). Format: ua:{sha256_hash}

  - `name: string`

    Human-readable name

  - `organization_id: string`

    Organization that owns this user agent

  - `slug: string`

    URL-safe identifier, unique within the zone

  - `updated_at: string`

    Entity update timestamp

  - `zone_id: string`

    Zone this user agent belongs to

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const userAgent = await client.zones.userAgents.retrieve('id', { zoneId: 'zoneId' });

console.log(userAgent.id);
```

## Domain Types

### User Agent

- `UserAgent`

  A User Agent represents a user agent (browser, desktop app, CLI tool) that can initiate user sessions via OAuth 2.0 Dynamic Client Registration.

  - `id: string`

    Unique identifier of the user agent

  - `created_at: string`

    Entity creation timestamp

  - `identifier: string`

    User agent identifier (serves as OAuth client_id). Format: ua:{sha256_hash}

  - `name: string`

    Human-readable name

  - `organization_id: string`

    Organization that owns this user agent

  - `slug: string`

    URL-safe identifier, unique within the zone

  - `updated_at: string`

    Entity update timestamp

  - `zone_id: string`

    Zone this user agent belongs to