> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create OAuth2 Secret

> Creates an OAuth2-type secret with automatic token refresh managed by KnoxCall

## Create OAuth2 Secret

```http theme={"dark"}
POST /v1/secrets/oauth2
```

Creates an OAuth2-type secret. KnoxCall stores the OAuth2 configuration encrypted at rest and manages token refresh automatically.

After creation, complete the authorization flow by redirecting your user to the `redirect_uri` returned in the response.

**Supported providers:** `google`, `github`, `salesforce`, `microsoft`, `slack`, `custom`

For `custom` providers, you must supply `auth_url` and `token_url`.

<Note>
  OAuth2 secrets require a **Pro or Enterprise** plan.
</Note>

### Request Body

| Field                 | Type      | Required    | Description                                                                                 |
| --------------------- | --------- | ----------- | ------------------------------------------------------------------------------------------- |
| `name`                | string    | Yes         | Secret name (spaces → underscores)                                                          |
| `provider`            | string    | Yes         | OAuth2 provider: `google`, `github`, `salesforce`, `microsoft`, `slack`, or `custom`        |
| `client_id`           | string    | Yes         | OAuth2 client ID from your provider's developer console                                     |
| `client_secret`       | string    | Conditional | OAuth2 client secret. Required unless using `mtls_certificate_id` or `grant_type: implicit` |
| `grant_type`          | string    | No          | `authorization_code` (default), `password`, or `implicit`                                   |
| `scopes`              | string\[] | No          | OAuth2 scopes to request. Defaults to the provider's recommended scopes                     |
| `auth_url`            | string    | No          | Authorization endpoint URL. Required for `custom` provider                                  |
| `token_url`           | string    | No          | Token endpoint URL. Required for `custom` provider                                          |
| `username`            | string    | Conditional | Username for `password` grant type                                                          |
| `password`            | string    | Conditional | Password for `password` grant type                                                          |
| `mtls_certificate_id` | uuid      | No          | ID of a `certificate`-type secret for mTLS auth to the token endpoint                       |
| `collection_id`       | uuid      | No          | Assign to a collection                                                                      |

### Response

```json theme={"dark"}
{
  "data": {
    "id": "a7c1d8f3-2e4b-4c6a-8d9e-1f3b5a7c9d2e",
    "name": "GOOGLE_OAUTH",
    "secret_type": "oauth2",
    "provider": "google",
    "redirect_uri": "https://api.knoxcall.com/auth/oauth2/callback/a7c1d8f3-...",
    "connection_status": "not_connected",
    "base_environment": "production",
    "collection_id": null,
    "mtls_certificate_id": null
  },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
```

<Note>
  Register the returned `redirect_uri` as an authorized redirect URL in your OAuth2 provider's app settings before redirecting users through the authorization flow.
</Note>

<CodeGroup>
  ```bash cURL — Authorization Code (Google) theme={"dark"}
  curl -X POST https://api.knoxcall.com/v1/secrets/oauth2 \
    -H "Authorization: Bearer tk_live_abc123..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "GOOGLE_OAUTH",
      "provider": "google",
      "client_id": "1234567890.apps.googleusercontent.com",
      "client_secret": "GOCSPX-abc123",
      "scopes": ["openid", "email", "profile"]
    }'
  ```

  ```bash cURL — Custom Provider theme={"dark"}
  curl -X POST https://api.knoxcall.com/v1/secrets/oauth2 \
    -H "Authorization: Bearer tk_live_abc123..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "MY_OAUTH",
      "provider": "custom",
      "client_id": "my-client-id",
      "client_secret": "my-client-secret",
      "auth_url": "https://auth.example.com/authorize",
      "token_url": "https://auth.example.com/token",
      "scopes": ["read", "write"]
    }'
  ```

  ```javascript Node.js theme={"dark"}
  const resp = await fetch("https://api.knoxcall.com/v1/secrets/oauth2", {
    method: "POST",
    headers: {
      Authorization: "Bearer tk_live_abc123...",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: "GOOGLE_OAUTH",
      provider: "google",
      client_id: "1234567890.apps.googleusercontent.com",
      client_secret: "GOCSPX-abc123",
      scopes: ["openid", "email", "profile"]
    })
  });
  const { data: secret } = await resp.json();
  // Redirect user to secret.redirect_uri to complete authorization
  ```
</CodeGroup>

You can also create OAuth2 secrets via `POST /v1/secrets` with `secret_type: "oauth2"` and the same body fields.

### Errors

| Status | Type               | Description                                                              |
| ------ | ------------------ | ------------------------------------------------------------------------ |
| 400    | `validation_error` | Missing required fields, invalid provider, or mTLS certificate not found |
| 403    | `plan_limit`       | OAuth2 secrets require Pro or Enterprise plan, or secret limit reached   |
| 409    | `conflict`         | A secret with this name already exists                                   |