Authentication Endpoints

We provide the following authentication endpoints to support our various authentication flows and access token requests:

/.well-known/oauth-authorization-server: OAuth 2.0 server metadata discovery
/auth/providers: lists all the configured providers and their URLs
/auth/token: returns an access and refresh token in exchange for either an ID token, authorization code, or username and password.
/auth/authorize/{name}: redirects to the provider's login page
/auth/callback/{name}: to be configured as the redirect URL with the provider
/auth/revoke: revoke a refresh token to prevent it from being used to get a new access token

`/.well-known/oauth-authorization-server`

This discovery endpoint allows OAuth clients to automatically find Keel's auth endpoints, as defined by RFC 8414 (opens in a new tab). This is particularly useful for MCP clients and other OAuth-compliant tools that support automatic server discovery.

GET /.well-known/oauth-authorization-server

Returns a JSON response with the server's OAuth 2.0 configuration:

{
  "issuer": "https://myapp.keel.so",
  "authorization_endpoint": "https://myapp.keel.so/auth/authorize/google",
  "token_endpoint": "https://myapp.keel.so/auth/token",
  "revocation_endpoint": "https://myapp.keel.so/auth/revoke",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token", "password", "token_exchange"],
  "code_challenge_methods_supported": ["S256", "plain"],
  "token_endpoint_auth_methods_supported": ["none"]
}

If multiple providers are configured, the first non-internal provider is used as the primary authorization_endpoint, and all providers are listed in a custom authorization_endpoints array.

`/auth/providers`

This endpoint lists all the configured 3rd-party authentication providers along with their authorize and callback URLs. When you make a request to this endpoint, you get a response similar to the following:

[
  {
    "name": "google",
    "type": "google",
    "authorizeUrl": "http://localhost:8000/auth/authorize/google",
    "callbackUrl": "http://localhost:8000/auth/callback/google"
  },
  {
    "name": "fb",
    "type": "facebook",
    "authorizeUrl": "http://localhost:8000/auth/authorize/fb",
    "callbackUrl": "http://localhost:8000/auth/callback/fb"
  }
]

`/auth/token`

The token endpoint is used to get access tokens, which are subsequently used to access your Keel API. To request an access token, make a POST request to /auth/token using either form-encoded data or as application/json. For example,

curl --request POST \
  --url 'http://localhost:8000/auth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=token_exchange \
  --data subject_token={{provider_id_token}}

Parameters

Parameter Name	Description
`grant_type`	Either `refresh_token`, `token_exchange`, `authorization_code`, or `password`
`refresh_token`	Only required for `refresh_token` grant
`subject_token`	Only required for `token_exchange` grant
`code`	Only required for `authorization_code` grant
`code_verifier`	Required for `authorization_code` grant when PKCE was used during authorization
`redirect_uri`	Required for `authorization_code` grant when a dynamic redirect URI was used during authorization. Must match the value sent in the authorize request.
`username`	Only required for `password` grant
`password`	Only required for `password` grant
`create_if_not_exists`	To create the identity or not during `token_exchange` or `password` flow. Default is `true`.

We currently support four types of grants:

The refresh_token grant type to refresh your access token.
The token_exchange grant type to perform ID Token authentication.
The authorization_code grant type to perform Single Sign-On authentication.
The password grant type to perform Password authentication.

Response

Regardless of the grant request, a successful response will return with a application/json HTTP 200 response, which will include the access token, refresh token, and expiry duration.

HTTP 200

{
  "access_token": "{{keel_access_token}}",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "{{keel_refresh_token}}",
  "identity_created": true
}

`/auth/authorize/{name}`

This endpoint initiates the Single Sign-On flow by redirecting the user to the provider's login page. {name} is the name of the provider as configured in your keelconfig.yaml.

Query Parameters

Parameter Name	Description
`redirect_uri`	The URL to redirect to after authentication. Only used when `redirectUrl` is not set in `keelconfig.yaml`. See dynamic redirect URIs.
`code_challenge`	A PKCE code challenge derived from a `code_verifier`
`code_challenge_method`	The method used to derive the code challenge. Either `S256` (recommended) or `plain`. Defaults to `plain`.
`state`	An opaque value for CSRF protection. Echoed back in the redirect to your `redirect_uri`. See state parameter.

`/auth/revoke`

The revoke endpoint is used revoke a refresh token. This will prevent anyone holding this token from using it to acquire a new access token from the token endpoint.

To revoke a refresh token, make a POST request to /auth/revoke using form-encoded data. For example,

curl --request POST \
  --url 'http://localhost:8000/auth/revoke' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token={{keel_refresh_token}}

The refresh token will no longer be available and any attempt to use it will fail. Users will need to re-authenticate to get a new refresh token.

Providers Testing