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

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

`/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
`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/revoke`

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.

Providers APIs