add server auth docs (#263)

* add server auth docs

* add more examples for oauth2 + JWT

Author: AdiSai

fern/docs.yml

@@ -387,6 +387,8 @@ navigation:
                 path: server-url/events.mdx
               - page: Developing Locally
                 path: server-url/developing-locally.mdx
+              - page: Server Authentication
+                path: server-url/server-authentication.mdx
 
       - section: Community
         collapsed: true

fern/server-url/server-authentication.mdx

@@ -0,0 +1,115 @@
+# Server Authentication
+
+When configuring webhooks for your assistant, you can authenticate your server endpoints using either a secret token, custom headers, or OAuth2. This ensures that only authorized requests from Vapi are processed by your server.
+
+## Credential Configuration
+
+Credentials can be configured at multiple levels:
+
+1. **Tool Call Level**: Create individual credentials for each tool call
+2. **Assistant Level**: Set credentials directly in the assistant configuration
+3. **Phone Number Level**: Configure credentials for specific phone numbers
+4. **Organization Level**: Manage credentials in the [API Keys page](https://dashboard.vapi.ai/keys)
+
+The order of precedence is:
+1. Tool call-level credentials
+2. Assistant-level credentials
+3. Phone number-level credentials
+4. Organization-level credentials from the API Keys page
+
+## Authentication Methods
+
+### Secret Token Authentication
+
+The simplest way to authenticate webhook requests is using a secret token. Vapi will include this token in the `X-Vapi-Signature` header of each request.
+
+#### Configuration
+
+```json
+{
+  "server": {
+    "url": "https://your-server.com/webhook",
+    "secret": "your-secret-token"
+  }
+}
+```
+
+### Custom Headers Authentication
+
+For more complex authentication scenarios, you can configure custom headers that Vapi will include with each webhook request.
+
+This could include short lived JWTs/API Keys passed along via the Authorization header, or any other header that your server checks for.
+
+#### Configuration
+
+```json
+{
+  "server": {
+    "url": "https://your-server.com/webhook",
+    "headers": {
+      "Authorization": "Bearer your-api-key",
+      "Custom-Header": "custom-value"
+    }
+  }
+}
+```
+
+### OAuth2 Authentication
+
+For OAuth2-protected webhook endpoints, you can configure OAuth2 credentials that Vapi will use to obtain and refresh access tokens.
+
+#### Configuration
+
+```json
+{
+  "server": {
+    "url": "https://your-server.com/webhook"
+  },
+  "credentials": {
+    "webhook": {
+      "type": "oauth2",
+      "clientId": "your-client-id",
+      "clientSecret": "your-client-secret",
+      "tokenUrl": "https://your-server.com/oauth/token",
+      "scope": "optional, only needed to specify which scopes to request access for"
+    }
+  }
+}
+```
+
+#### OAuth2 Flow
+
+1. Vapi makes a request to your token endpoint with client credentials
+2. Your server validates the credentials and returns an access token
+3. Vapi includes the access token in the Authorization header for webhook requests
+4. Your server validates the access token before processing the webhook
+5. When the token expires, Vapi automatically requests a new one
+
+#### OAuth2 Token Response Format
+
+Your server should return a JSON response with the following format:
+
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",  // Optional
+  "scope": "read write"  // Optional, only if scope was requested
+}
+```
+
+Example error response:
+
+```json
+{
+  "error": "invalid_client",
+  "error_description": "Invalid client credentials"
+}
+```
+
+Common error types:
+- `invalid_client`: Invalid client credentials
+- `invalid_grant`: Invalid or expired refresh token
+- `invalid_scope`: Invalid scope requested
+- `unauthorized_client`: Client not authorized for this grant type