# Sign in with Tickwire (OAuth) and connected apps (AI agents)

> Tickwire API reference, generated from the OpenAPI document the services export. Base URL: https://api.tickwire.io. Replace YOUR_API_KEY and YOUR_ACCOUNT_ID with your own values; use a sandbox key (twsk_…) to experiment.

Source: https://tickwire.io/docs/reference/oauth/

### GET /.well-known/oauth-authorization-server

**As Metadata**

Auth: `X-API-Key`

RFC 8414 Authorization Server Metadata.

Responses:

- `200` Successful Response

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X GET 'https://api.tickwire.io/.well-known/oauth-authorization-server' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "GET",
        "/.well-known/oauth-authorization-server",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("GET", "/.well-known/oauth-authorization-server");
console.log(result);
tw.close();
```

### GET /oauth/authorize

**Authorize**

Auth: `X-API-Key`

Validate the request, then send the browser to the consent page.

Responses:

- `200` Successful Response

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X GET 'https://api.tickwire.io/oauth/authorize' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "GET",
        "/oauth/authorize",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("GET", "/oauth/authorize");
console.log(result);
tw.close();
```

### POST /oauth/consent/decide

**Consent Decide**

Auth: `X-API-Key`

Approve or deny; answers where to send the browser next.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `X-Reason` | header | `string \| null` | no |  |
| `X-Tickwire-CSRF` | header | `string \| null` | no |  |

Request body: `object` (required)

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X POST 'https://api.tickwire.io/oauth/consent/decide' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-Reason: why you are doing this' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "POST",
        "/oauth/consent/decide",
        json={},
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("POST", "/oauth/consent/decide", {
  body: {},
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```

### POST /oauth/consent/view

**Consent View**

Auth: `X-API-Key`

What the consent page shows, plus a consent token bound to this session.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `X-Tickwire-CSRF` | header | `string \| null` | no |  |

Request body: `object` (required)

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X POST 'https://api.tickwire.io/oauth/consent/view' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "POST",
        "/oauth/consent/view",
        json={},
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("POST", "/oauth/consent/view", {
  body: {},
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```

### POST /oauth/register

**Register**

Auth: `X-API-Key`

RFC 7591 Dynamic Client Registration.

Responses:

- `201` Successful Response

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X POST 'https://api.tickwire.io/oauth/register' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "POST",
        "/oauth/register",
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("POST", "/oauth/register", {
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```

### POST /oauth/revoke

**Revoke**

Auth: `X-API-Key`

RFC 7009 token revocation.

Responses:

- `200` Successful Response

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X POST 'https://api.tickwire.io/oauth/revoke' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "POST",
        "/oauth/revoke",
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("POST", "/oauth/revoke", {
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```

### POST /oauth/token

**Token**

Auth: `X-API-Key`

Exchange an authorization code or a refresh token for tokens. Never
retry a refresh token that was refused: start a new sign-in instead.

Responses:

- `200` Successful Response

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X POST 'https://api.tickwire.io/oauth/token' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "POST",
        "/oauth/token",
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("POST", "/oauth/token", {
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```

### GET /v1/connected-apps

**List Apps**

Auth: `X-API-Key`

Apps connected to this tenant through Sign in with Tickwire, oldest
first. Cursor-paginated: `{apps, has_more, next_cursor}`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `include_ended` | query | `boolean` | no |  |
| `limit` | query | `integer` | no | Page size, 1..500 (default 100). |
| `cursor` | query | `string \| null` | no | The next_cursor of the previous page, unchanged. |

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X GET 'https://api.tickwire.io/v1/connected-apps' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "GET",
        "/v1/connected-apps",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("GET", "/v1/connected-apps");
console.log(result);
tw.close();
```

### DELETE /v1/connected-apps/{grant_id}

**Disconnect App**

Auth: `X-API-Key`

Disconnect: revoke the app's agent key and all of its tokens.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `grant_id` | path | `string` | yes |  |
| `X-Actor` | header | `string \| null` | no |  |
| `X-Reason` | header | `string \| null` | no |  |

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X DELETE 'https://api.tickwire.io/v1/connected-apps/GRANT_ID' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-Reason: why you are doing this'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "DELETE",
        "/v1/connected-apps/GRANT_ID",
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("DELETE", "/v1/connected-apps/GRANT_ID", {
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```