# CLI sign-ins

A CLI sign-in is one computer where `clanker auth login` signed in as you. The website's Security settings list them too.

## The CliSession object

One computer where the `clanker` CLI signed in as you.

### Attributes

- `id` (string, required): Unique ID of the CLI sign-in.
- `createdAt` (string, required): When `clanker auth login` signed in, as an ISO 8601 timestamp.
- `expiresAt` (string, required): When the sign-in ends unless the CLI is used again, as an ISO 8601 timestamp.

### Example

```json
{
  "id": "Cs8vN1qLm3Zx",
  "createdAt": "2026-10-01T16:20:00.000Z",
  "expiresAt": "2026-10-14T09:05:12.000Z"
}
```

## List CLI sign-ins

`GET /v1/me/cli-sessions`

Returns the computers where the `clanker` CLI is signed in as you. Account API keys have none.

### Returns

Returns an object with these fields. The status is 200.

- `sessions` (array of objects, required): Your CLI sign-ins that have not ended. See [the CliSession object](https://docs.clankership.com/api/cli-sessions/object.md).
  - `id` (string, required): Unique ID of the CLI sign-in.
  - `createdAt` (string, required): When `clanker auth login` signed in, as an ISO 8601 timestamp.
  - `expiresAt` (string, required): When the sign-in ends unless the CLI is used again, as an ISO 8601 timestamp.

### Request

```bash
curl https://api.clankership.com/v1/me/cli-sessions \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "sessions": [
    {
      "id": "Cs8vN1qLm3Zx",
      "createdAt": "2026-10-01T16:20:00.000Z",
      "expiresAt": "2026-10-14T09:05:12.000Z"
    }
  ]
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Revoke a CLI sign-in

`POST /v1/me/cli-sessions/{session}/revoke`

Ends one of your CLI sign-ins, so the CLI on that computer must sign in again. Fails with NotFound when the sign-in is not yours or has already ended.

### Parameters

- `session` (string, in path, required): The sign-in's ID, such as Cs8vN1qLm3Zx.

### Returns

Returns an object with these fields. The status is 200.

- `ok` (boolean, required): Always true: the change was made. Always `true`.

### Request

```bash
curl -X POST https://api.clankership.com/v1/me/cli-sessions/{session}/revoke \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "ok": true
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.