Authentication Endpoints

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

  • /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


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/facebook",
    "callbackUrl": "http://localhost:8000/auth/callback/facebook"


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


Parameter NameDescription
grant_typeEither refresh_token, token_exchange, authorization_code, or password
refresh_tokenOnly required for refresh_token grant
subject_tokenOnly required for token_exchange grant
codeOnly required for authorization_code grant
usernameOnly required for password grant
passwordOnly required for password grant
create_if_not_existsTo create the identity or not during token_exchange or password flow. Default is true.

We currently support four types of grants:


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


The revoke endpoint is used revoke a refresh token. This will prevent anyone holding this token from using it to aquire 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.