### Start authorization flow with GET authorize endpoint

Source: https://www.kaggle.com/docs/api

Redirects the user to Kaggle's authorization endpoint. Required query parameters include client_id, redirect_uri, scope, state, response_type, response_mode, and for public clients code_challenge and code_challenge_method.

```http
GET https://www.kaggle.com/api/v1/oauth2/authorize
```

--------------------------------

### Receive authorization code callback

Source: https://www.kaggle.com/docs/api

Example callback URL after user approval. Verify that the state parameter matches the one sent to prevent CSRF attacks.

```http
http://localhost:8080/callback?code=<authorization_code>&state=xyzABC123456789012345
```

--------------------------------

### GET /.well-known/oauth-protected-resource

Source: https://www.kaggle.com/docs/api

Retrieves metadata about the protected resource (Kaggle API). This is a discovery endpoint for OAuth 2.0 protected resources.

```APIDOC
## GET https://www.kaggle.com/.well-known/oauth-protected-resource

### Description
Retrieves metadata about the protected resource (Kaggle API).

### Method
GET

### Endpoint
https://www.kaggle.com/.well-known/oauth-protected-resource

```

--------------------------------

### Token exchange response

Source: https://www.kaggle.com/docs/api

Example response from the token endpoint containing access and refresh tokens, token type, expiration time, user details, and granted scopes.

```json
{
  "access_token": "KGAT_...",
  "refresh_token": "KGRT_...",
  "token_type": "Bearer",
  "expires_in": 10800,
  "username": "johndoe",
  "user_id": 12345,
  "scope": "datasets.get:* models.get:*"
}
```

--------------------------------

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

Source: https://www.kaggle.com/docs/api

Retrieves OAuth 2.0 server metadata including supported endpoints, grant types, and scopes. This is a discovery endpoint for OAuth 2.0 clients.

```APIDOC
## GET https://www.kaggle.com/.well-known/oauth-authorization-server

### Description
Retrieves OAuth 2.0 server metadata including supported endpoints, grant types, and scopes.

### Method
GET

### Endpoint
https://www.kaggle.com/.well-known/oauth-authorization-server

```

--------------------------------

### Active Token Introspection Response

Source: https://www.kaggle.com/docs/api

Example introspection response for an active token, showing the token is valid and includes user and scope information.

```json
{
  "active": true,
  "username": "johndoe",
  "user_id": 12345,
  "scope": "datasets.viewer:*",
  "exp": 1705719600
}
```

--------------------------------

### Invalid Token Introspection Response

Source: https://www.kaggle.com/docs/api

Example introspection response for an expired, revoked, or otherwise invalid token.

```json
{
  "active": false
}
```

--------------------------------

### Generate PKCE code verifier and challenge

Source: https://www.kaggle.com/docs/api

Generates a PKCE code verifier and challenge using Python's secrets, hashlib, and base64 modules. Required for public clients; organization clients should skip this step.

```python
import secrets
import hashlib
import base64

# Generate a random code_verifier (43-128 characters)
code_verifier = secrets.token_urlsafe(32)

# Create code_challenge using SHA-256
code_challenge = base64.urlsafe_b64encode(
    hashlib.sha256(code_verifier.encode()).digest()
).decode().rstrip('=')
```

--------------------------------

### Public client token exchange (JSON)

Source: https://www.kaggle.com/docs/api

Public client token exchange using JSON body. Includes code_verifier for PKCE; no authentication header is required.

```bash
curl -X POST https://www.kaggle.com/api/v1/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "<authorization_code>",
    "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
  }'
```

--------------------------------

### Public client token exchange (form-urlencoded)

Source: https://www.kaggle.com/docs/api

Public client token exchange using form-urlencoded body. Includes code_verifier for PKCE; no authentication header is required.

```bash
curl -X POST https://www.kaggle.com/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=<authorization_code>" \
  -d "code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
```

--------------------------------

### Organization client token exchange (JSON)

Source: https://www.kaggle.com/docs/api

Organization client token exchange using JSON body. Uses HTTP Basic authentication with the organization owner's credentials and must not send code_verifier.

```bash
curl -X POST https://www.kaggle.com/api/v1/oauth2/token \
  -u "<org_owner_username>:<org_owner_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "<authorization_code>"
  }'
```

--------------------------------

### OAuth 2.0 Discovery: Authorization Server Metadata

Source: https://www.kaggle.com/docs/api

Retrieves OAuth 2.0 server metadata including supported endpoints, grant types, and scopes for the Kaggle authorization server.

```http
GET https://www.kaggle.com/.well-known/oauth-authorization-server
```

--------------------------------

### OAuth 2.0 Discovery: Protected Resource Metadata

Source: https://www.kaggle.com/docs/api

Retrieves metadata about the protected resource (the Kaggle API) for OAuth 2.0 resource server discovery.

```http
GET https://www.kaggle.com/.well-known/oauth-protected-resource
```

--------------------------------

### Use Access Token in API Request

Source: https://www.kaggle.com/docs/api

Include the access token in API requests using the Authorization header with the Bearer scheme.

```bash
curl https://www.kaggle.com/api/v1/datasets/list \
  -H "Authorization: Bearer KGAT_..."
```

--------------------------------

### Organization client token exchange (form-urlencoded)

Source: https://www.kaggle.com/docs/api

Organization client token exchange using form-urlencoded body. Uses HTTP Basic authentication with the organization owner's credentials and must not send code_verifier.

```bash
curl -X POST https://www.kaggle.com/api/v1/oauth2/token \
  -u "<org_owner_username>:<org_owner_api_key>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=<authorization_code>"
```

--------------------------------

### OAuth2 Token Management and Authenticated API Usage

Source: https://www.kaggle.com/docs/api

Code snippets for OAuth2 token management and authenticated API usage.

```APIDOC
## [POST] /api/v1/oauth2/token

### Description
Refreshes an expired access token using a refresh token. The request can be sent as form-urlencoded or JSON, and does not require client authentication.

### Method
POST

### Endpoint
https://www.kaggle.com/api/v1/oauth2/token

### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be set to `refresh_token`.
- **refresh_token** (string) - Required - The refresh token (e.g., `KGRT_...`).

### Request Example
```
curl -X POST https://www.kaggle.com/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=KGRT_..."
```

### Response
#### Success Response (200)
Returns a new access token and possibly a new refresh token. The exact response fields are not specified in the source.

#### Response Example
Not provided in the source.

```

```APIDOC
## [POST] /api/v1/oauth2/token

### Description
Validates and inspects an access token or refresh token. The request can be sent as form-urlencoded or JSON, and returns token metadata.

### Method
POST

### Endpoint
https://www.kaggle.com/api/v1/oauth2/token

### Parameters
#### Request Body
- **token** (string) - Required - The access token or refresh token to inspect.

### Request Example
```
curl -X POST https://www.kaggle.com/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=<access_token_or_refresh_token>"
```

### Response
#### Success Response (200)
Returns a JSON object with token metadata. For an active token, the response includes `active`, `username`, `user_id`, `scope`, and `exp`. For an invalid token, only `active` is returned.

#### Response Example
```
{
  "active": true,
  "username": "johndoe",
  "user_id": 12345,
  "scope": "datasets.viewer:*",
  "exp": 1705719600
}
```

```

```APIDOC
## [POST] /api/v1/oauth2/introspect

### Description
Validates and inspects an access token or refresh token. This is the JSON endpoint equivalent to the form-urlencoded token introspection request.

### Method
POST

### Endpoint
https://www.kaggle.com/api/v1/oauth2/introspect

### Parameters
#### Request Body
- **token** (string) - Required - The access token or refresh token to inspect.

### Request Example
```
curl -X POST https://www.kaggle.com/api/v1/oauth2/introspect \
  -H "Content-Type: application/json" \
  -d '{"token": "<access_token_or_refresh_token>"}'
```

### Response
#### Success Response (200)
Returns a JSON object with token metadata. For an active token, the response includes `active`, `username`, `user_id`, `scope`, and `exp`. For an invalid token, only `active` is returned.

#### Response Example
```
{
  "active": true,
  "username": "johndoe",
  "user_id": 12345,
  "scope": "datasets.viewer:*",
  "exp": 1705719600
}
```

```

```APIDOC
## [GET] /api/v1/datasets/list

### Description
Lists datasets. This endpoint requires an access token in the Authorization header.

### Method
GET

### Endpoint
https://www.kaggle.com/api/v1/datasets/list

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token (e.g., `Bearer KGAT_...`).

### Request Example
```
curl https://www.kaggle.com/api/v1/datasets/list \
  -H "Authorization: Bearer KGAT_..."
```

### Response
#### Success Response (200)
Not specified in the source.

#### Response Example
Not provided in the source.

```

--------------------------------

### OAuth2 Authorization Flow

Source: https://www.kaggle.com/docs/api

Code snippets for the OAuth2 authorization flow endpoints.

```APIDOC
## [GET] https://www.kaggle.com/api/v1/oauth2/authorize

### Description
Starts the OAuth2 authorization flow by redirecting the user to Kaggle's consent screen.

### Method
GET

### Endpoint
https://www.kaggle.com/api/v1/oauth2/authorize

### Parameters
#### Query Parameters
- **client_id** (string) - Required - Your registered client ID
- **redirect_uri** (string) - Required - Must match a registered redirect URI
- **scope** (string) - Required - Space-separated list of scopes
- **state** (string) - Required - Random string (20-128 chars) for CSRF protection
- **response_type** (string) - Required - Must be "code"
- **response_mode** (string) - Required - Must be "query"
- **code_challenge** (string) - Required for public clients - Base64URL-encoded SHA-256 hash of code_verifier
- **code_challenge_method** (string) - Required for public clients - Must be "S256"
```

```APIDOC
## [POST] https://www.kaggle.com/api/v1/oauth2/token

### Description
Exchanges an authorization code for access and refresh tokens. The request can be sent with Content-Type: application/x-www-form-urlencoded or application/json.

### Method
POST

### Endpoint
https://www.kaggle.com/api/v1/oauth2/token

### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be "authorization_code"
- **code** (string) - Required - The authorization code from the callback
- **code_verifier** (string) - Public clients only - Original code_verifier used to generate code_challenge. Must not be sent by organization clients.
- **client_id** (string) - Optional - Your client ID
- **redirect_uri** (string) - Optional - The redirect URI used in the authorization request

### Request Example
```
curl -X POST https://www.kaggle.com/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=<authorization_code>" \
  -d "code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
```

### Response
#### Success Response (200)
- **access_token** (string) - The access token
- **refresh_token** (string) - The refresh token
- **token_type** (string) - Token type, e.g., "Bearer"
- **expires_in** (integer) - Token expiration time in seconds
- **username** (string) - The authenticated user's username
- **user_id** (integer) - The authenticated user's ID
- **scope** (string) - Space-separated list of granted scopes

#### Response Example
```
{
  "access_token": "KGAT_...",
  "refresh_token": "KGRT_...",
  "token_type": "Bearer",
  "expires_in": 10800,
  "username": "johndoe",
  "user_id": 12345,
  "scope": "datasets.get:* models.get:*"
}
```
```

--------------------------------

### Refresh Access Token with curl

Source: https://www.kaggle.com/docs/api

Refresh an expired access token using the refresh token. Both form-urlencoded and JSON encodings are equivalent; refresh token requests do not require client authentication.

```bash
curl -X POST https://www.kaggle.com/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=KGRT_..."
```

```bash
curl -X POST https://www.kaggle.com/api/v1/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "refresh_token", "refresh_token": "KGRT_..."}'
```

--------------------------------

### Token Introspection with curl

Source: https://www.kaggle.com/docs/api

Validate and inspect tokens using RFC 7662 token introspection. Both encodings return the same JSON response.

```bash
curl -X POST https://www.kaggle.com/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=<access_token_or_refresh_token>"
```

```bash
curl -X POST https://www.kaggle.com/api/v1/oauth2/introspect \
  -H "Content-Type: application/json" \
  -d '{"token": "<access_token_or_refresh_token>"}'
```

--------------------------------

### Exchange code for tokens with POST token endpoint

Source: https://www.kaggle.com/docs/api

Endpoint for exchanging the authorization code for tokens. The same request may also be sent with Content-Type: application/json and a JSON body.

```http
POST https://www.kaggle.com/api/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.