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. For non-interactive grant types (client_credentials, password), tokens are fetched immediately without any redirect. 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), `client_credentials`, `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"]
  }'

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

Documentation Index