using-oauth2

# OAuth2 App Integration Skill

Use this skill when the user provides an OAuth2 application, OAuth2 documentation, or asks you to call an API that requires OAuth2 authorization.

OAuth2 app APIs are not registered as individual tools. The standard parts are obtaining a valid access token and,
when possible, sending the business HTTP request through the visible `oauth2_request` transport tool.
For unsupported cases, keep using `sdk.oauth2.get_access_token()` and write the HTTP request yourself in Code Mode
according to the provider's API docs.

## How it works

OAuth2 capabilities are exposed as Code Mode tools (`oauth2_*`). They are not directly callable as standalone tool calls. Invoke them through `run_sdk_snippet` and `sdk.tool.call`:

```python
run_sdk_snippet(python_code="""
from sdk.tool import tool

result = tool.call("oauth2_list_apps")
print(result.content)
""")
```

Business API calls should use `oauth2_request` when it supports the provider's request shape.
Minimal GET example:

```python
run_sdk_snippet(python_code="""
from sdk.tool import tool

result = tool.call("oauth2_request", {
    "app_name": "<app_name>",
    "method": "GET",
    "url": "<api_url>",
    "headers": {
        "Accept": "application/json",
    }
})
print(result.content)
""")
```

This creates a visible API request card for the user.

`oauth2_request` parameters:

| Parameter | Required | Meaning |
|-----------|----------|---------|
| `app_name` | Yes | Registered and authorized OAuth2 app name. |
| `method` | No | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. Defaults to `GET`. |
| `url` | Yes | Business API URL from the provider docs. |
| `headers` | No | Business headers only. Do not include OAuth2 credential headers. |
| `query` | No | URL query parameters. |
| `json_body` | No | JSON request body. Mutually exclusive with `form_body`. |
| `form_body` | No | Form request body. Mutually exclusive with `json_body`. |
| `auth` | No | Access token injection settings. Defaults to `Authorization: Bearer <access_token>`. |
| `timeout` | No | HTTP timeout in seconds. Defaults to `30`, maximum `120`. |

`oauth2_request` returns structured data in `result.data`. Important fields include:

| Return field | Meaning |
|--------------|---------|
| `status_code` | HTTP response status code. |
| `request_duration_ms` | Business HTTP request duration in milliseconds. |
| `body_text` | Response body text, truncated when it is too large. |
| `request_headers` | Redacted request headers. |
| `response_headers` | Redacted response headers. |

Full `oauth2_request` parameter template:

```python
run_sdk_snippet(python_code="""
from sdk.tool import tool

result = tool.call("oauth2_request", {
    # Required: the registered and authorized OAuth2 app name.
    "app_name": "<app_name>",

    # Optional: GET, POST, PUT, PATCH, or DELETE. Defaults to GET.
    "method": "POST",

    # Required: business API URL from the provider docs.
    "url": "<api_url_from_provider_docs>",

    # Optional: business headers only. Do not include Authorization, Access-Token, or token headers.
    "headers": {
        "Accept": "application/json",
        "Content-Type": "application/json",
    },

    # Optional: URL query parameters.
    "query": {
        "page": 1,
        "page_size": 20,
    },

    # Optional: JSON request body. Mutually exclusive with form_body.
    "json_body": {
        "name": "<value>",
    },

    # Optional: token injection settings. Omit this for Authorization: Bearer <access_token>.
    # Use type=header for providers that require headers such as Access-Token.
    "auth": {
        "type": "bearer",
        "header_name": "Authorization",
        "prefix": "Bearer ",
    },

    # Optional: HTTP timeout in seconds. Maximum 120. Defaults to 30.
    "timeout": 30,
})
print(result.content)
print("request_duration_ms:", result.data.get("request_duration_ms"))
""")
```

Form body variant:

```python
run_sdk_snippet(python_code="""
from sdk.tool import tool

result = tool.call("oauth2_request", {
    "app_name": "<app_name>",
    "method": "POST",
    "url": "<api_url_from_provider_docs>",
    "headers": {
        "Accept": "application/json",
        "Content-Type": "application/x-www-form-urlencoded",
    },
    "form_body": {
        "field": "<value>",
    },
    "auth": {
        "type": "header",
        "header_name": "Access-Token",
        "prefix": "",
    },
    "timeout": 30,
})
print(result.content)
print("request_duration_ms:", result.data.get("request_duration_ms"))
""")
```

If `oauth2_request` cannot express the provider-specific request, use `run_python_snippet` and fall back to
`sdk.oauth2.get_access_token()`. This keeps the request output visible to the user. Do not print the access token.

## Available OAuth2 tools

| Tool name | Purpose |
|-----------|---------|
| `oauth2_list_apps` | List registered OAuth2 apps and current authorization status. Start here. |
| `oauth2_upsert_app` | Register or update a user-provided OAuth2 app definition. |
| `oauth2_get_redirect_uri` | Get the redirect URI only when the user explicitly asks for it. |
| `oauth2_remove_app` | Remove one or more OAuth2 apps and their stored authorization data. |
| `oauth2_start_authorization` | Generate an authorization URL, create a pending session, and start background authorization checking. |
| `oauth2_check_authorization` | Idempotently check authorization status when confirmation or recovery is needed. |
| `oauth2_request` | Send a visible OAuth2 HTTP request for business APIs. Prefer this when supported. |
| `oauth2_list_api_docs` | Search the recorded API documentation library for this OAuth2 app. |
| `oauth2_get_api_doc` | Load one recorded OpenAPI operation by `operation_id`. |
| `oauth2_upsert_api_doc` | Create or update one recorded OpenAPI operation after user confirmation. |
| `oauth2_remove_api_doc` | Remove one or more recorded OpenAPI operations under one app by `operation_ids`. |

## Standard workflow

1