The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
feat(docs): `token_endpoint_auth_method` in OAuth server docs (#43128)
Cemal Kılıçd810b7772b66
diff --git a/apps/docs/content/guides/auth/oauth-server/getting-started.mdx b/apps/docs/content/guides/auth/oauth-server/getting-started.mdxindex 95ecc5a595e..b65a671d198 100644--- a/apps/docs/content/guides/auth/oauth-server/getting-started.mdx+++ b/apps/docs/content/guides/auth/oauth-server/getting-started.mdx@@ -491,6 +491,22 @@ Store the client secret securely. It will only be shown once. If you lose it, yo</Admonition>+#### Token endpoint authentication method++When a client exchanges an authorization code or refreshes a token, it must authenticate with the token endpoint. The `token_endpoint_auth_method` controls how this authentication happens:++| Method | Description | Used by |+| --- | --- | --- |+| `none` | No client authentication. Only `client_id` is sent in the request body. | Public clients (required) |+| `client_secret_basic` | Client credentials sent via HTTP Basic auth (`Authorization: Basic <base64(client_id:client_secret)>`). **This is the default for confidential clients.** | Confidential clients |+| `client_secret_post` | Client credentials sent in the request body (`client_id` and `client_secret` as form parameters). | Confidential clients |++**Defaults:** Public clients default to `none`. Confidential clients default to `client_secret_basic` (per [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591#section-2)).++**Constraints:** Public clients must use `none`. Confidential clients cannot use `none`.++You can set this when registering a client via the dashboard or programmatically. See [OAuth Flows](/docs/guides/auth/oauth-server/oauth-flows#step-5-token-exchange) for examples of each method in action.+</TabPanel><TabPanel id="programmatically" label="Programmatically">@@ -518,6 +534,8 @@ const { data, error } = await supabase.auth.admin.oauth.createClient({name: 'My Third-Party App',redirect_uris: ['https://my-app.com/auth/callback', 'https://my-app.com/auth/silent-callback'],client_type: 'confidential',+ // Optional: defaults to 'client_secret_basic' for confidential, 'none' for public+ token_endpoint_auth_method: 'client_secret_basic',})if (error) {@@ -548,7 +566,9 @@ response = supabase.auth.admin.oauth.create_client({'https://my-app.com/auth/callback','https://my-app.com/auth/silent-callback'],- 'client_type': 'confidential'+ 'client_type': 'confidential',+ # Optional: defaults to 'client_secret_basic' for confidential, 'none' for public+ 'token_endpoint_auth_method': 'client_secret_basic'})print('Client created:', response)@@ -572,7 +592,8 @@ curl -X POST 'https://<project-ref>.supabase.co/auth/v1/admin/oauth/clients' \"https://my-app.com/auth/callback","https://my-app.com/auth/silent-callback"],- "client_type": "confidential"+ "client_type": "confidential",+ "token_endpoint_auth_method": "client_secret_basic"}'```@@ -585,7 +606,8 @@ curl -X POST 'http://localhost:54321/auth/v1/admin/oauth/clients' \-d '{"name": "Local Dev App","redirect_uris": ["http://localhost:3000/auth/callback"],- "client_type": "confidential"+ "client_type": "confidential",+ "token_endpoint_auth_method": "client_secret_post"}'```@@ -598,6 +620,7 @@ Response:"name": "My Third-Party App","redirect_uris": ["https://my-app.com/auth/callback", "https://my-app.com/auth/silent-callback"],"client_type": "confidential",+ "token_endpoint_auth_method": "client_secret_basic","created_at": "2025-01-15T10:30:00.000Z"}```diff --git a/apps/docs/content/guides/auth/oauth-server/oauth-flows.mdx b/apps/docs/content/guides/auth/oauth-server/oauth-flows.mdxindex 028634e88c7..ec39a958843 100644--- a/apps/docs/content/guides/auth/oauth-server/oauth-flows.mdx+++ b/apps/docs/content/guides/auth/oauth-server/oauth-flows.mdx@@ -230,7 +230,11 @@ The error parameters allow clients to display relevant error messages to users:### Step 5: Token exchange-The client exchanges the authorization code for tokens by making a POST request to the token endpoint:+The client exchanges the authorization code for tokens by making a POST request to the token endpoint. How the client authenticates depends on its `token_endpoint_auth_method` (set during [client registration](/docs/guides/auth/oauth-server/getting-started#token-endpoint-authentication-method)).++#### Public clients (`token_endpoint_auth_method: none`)++Public clients send only the `client_id` in the request body with no secret:```bashcurl -X POST 'https://<project-ref>.supabase.co/auth/v1/oauth/token' \@@ -242,7 +246,29 @@ curl -X POST 'https://<project-ref>.supabase.co/auth/v1/oauth/token' \-d 'code_verifier=<code-verifier>'```-For confidential clients (with client secret):+#### Confidential clients (`token_endpoint_auth_method: client_secret_basic`)++This is the **default** for confidential clients. Credentials are sent via the `Authorization` header using HTTP Basic authentication (base64-encoded `client_id:client_secret`):++```bash+curl -X POST 'https://<project-ref>.supabase.co/auth/v1/oauth/token' \+ -H 'Content-Type: application/x-www-form-urlencoded' \+ -u '<client-id>:<client-secret>' \+ -d 'grant_type=authorization_code' \+ -d 'code=<authorization-code>' \+ -d 'redirect_uri=<redirect-uri>' \+ -d 'code_verifier=<code-verifier>'+```++<Admonition type="note">++The `-u` flag in cURL automatically encodes the credentials and sets the `Authorization: Basic <base64(client_id:client_secret)>` header. If you're not using cURL, you must base64-encode the `client_id:client_secret` string yourself.++</Admonition>++#### Confidential clients (`token_endpoint_auth_method: client_secret_post`)++Credentials are sent as form parameters in the request body:```bashcurl -X POST 'https://<project-ref>.supabase.co/auth/v1/oauth/token' \@@ -261,7 +287,37 @@ curl -X POST 'https://<project-ref>.supabase.co/auth/v1/oauth/token' \// Retrieve the code verifier from storageconst codeVerifier = sessionStorage.getItem('code_verifier')-// Exchange code for tokens+// --- Public clients (token_endpoint_auth_method: none) ---+const response = await fetch(`https://<project-ref>.supabase.co/auth/v1/oauth/token`, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/x-www-form-urlencoded',+ },+ body: new URLSearchParams({+ grant_type: 'authorization_code',+ code: authorizationCode,+ client_id: '<client-id>',+ redirect_uri: '<redirect-uri>',+ code_verifier: codeVerifier,+ }),+})++// --- Confidential clients (token_endpoint_auth_method: client_secret_basic) ---+const response = await fetch(`https://<project-ref>.supabase.co/auth/v1/oauth/token`, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/x-www-form-urlencoded',+ Authorization: 'Basic ' + btoa('<client-id>:<client-secret>'),+ },+ body: new URLSearchParams({+ grant_type: 'authorization_code',+ code: authorizationCode,+ redirect_uri: '<redirect-uri>',+ code_verifier: codeVerifier,+ }),+})++// --- Confidential clients (token_endpoint_auth_method: client_secret_post) ---const response = await fetch(`https://<project-ref>.supabase.co/auth/v1/oauth/token`, {method: 'POST',headers: {@@ -271,6 +327,7 @@ const response = await fetch(`https://<project-ref>.supabase.co/auth/v1/oauth/togrant_type: 'authorization_code',code: authorizationCode,client_id: '<client-id>',+ client_secret: '<client-secret>',redirect_uri: '<redirect-uri>',code_verifier: codeVerifier,}),@@ -377,7 +434,9 @@ Clients should refresh access tokens when:### Refresh request-Make a POST request to the token endpoint with the refresh token:+Make a POST request to the token endpoint with the refresh token. The client authenticates the same way as during the [token exchange](#step-5-token-exchange), based on its `token_endpoint_auth_method`.++#### Public clients (`token_endpoint_auth_method: none`)```bashcurl -X POST 'https://<project-ref>.supabase.co/auth/v1/oauth/token' \@@ -387,7 +446,17 @@ curl -X POST 'https://<project-ref>.supabase.co/auth/v1/oauth/token' \-d 'client_id=<client-id>'```-For confidential clients:+#### Confidential clients (`token_endpoint_auth_method: client_secret_basic`)++```bash+curl -X POST 'https://<project-ref>.supabase.co/auth/v1/oauth/token' \+ -H 'Content-Type: application/x-www-form-urlencoded' \+ -u '<client-id>:<client-secret>' \+ -d 'grant_type=refresh_token' \+ -d 'refresh_token=<refresh-token>'+```++#### Confidential clients (`token_endpoint_auth_method: client_secret_post`)```bashcurl -X POST 'https://<project-ref>.supabase.co/auth/v1/oauth/token' \@@ -401,6 +470,7 @@ curl -X POST 'https://<project-ref>.supabase.co/auth/v1/oauth/token' \#### Example in JavaScript```javascript+// Public clients (token_endpoint_auth_method: none)async function refreshAccessToken(refreshToken) {const response = await fetch(`https://<project-ref>.supabase.co/auth/v1/oauth/token`, {method: 'POST',@@ -420,6 +490,27 @@ async function refreshAccessToken(refreshToken) {return await response.json()}++// Confidential clients (token_endpoint_auth_method: client_secret_basic)+async function refreshAccessTokenConfidential(refreshToken) {+ const response = await fetch(`https://<project-ref>.supabase.co/auth/v1/oauth/token`, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/x-www-form-urlencoded',+ Authorization: 'Basic ' + btoa('<client-id>:<client-secret>'),+ },+ body: new URLSearchParams({+ grant_type: 'refresh_token',+ refresh_token: refreshToken,+ }),+ })++ if (!response.ok) {+ throw new Error('Failed to refresh token')+ }++ return await response.json()+}```### Refresh response