Create OAuth2 Secret

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.

OAuth2 secrets require a Pro or Enterprise plan.

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

{
  "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" }
}

Register the returned redirect_uri as an authorized redirect URL in your OAuth2 provider’s app settings before redirecting users through the authorization flow.

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"]
  }'

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"]
  }'

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

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

Overview

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Create OAuth2 Secret