OAuth2 API Reference

These APIs facilitate user authorization through the OAuth2 flow. For a guide on getting started with OAuth2, check out our OAuth2 Guide.

GET{AUTH_URL}/propelauth/oauth/authorize

Authorize Endpoint

This redirects the user to the PropelAuth login page. This should be done in the browser.

The authorize endpoint is compatible with the code response type. Once the user has logged in successfully, it will redirect the user to the provided redirect_uri and include a code parameter in the URL.

Query Parameters

Name
redirect_uri *
Description
The URL where the user is directed to after a successful login. The provided URL must be set in the OAuth Config page.
Name
client_id *
Description
Found in the OAuth Config page.
Name
response_type *
Description
Must be set to code.
Name
state *
Description
A randomly generated string used to guard against CSRF attacks. After the user successfully logs in, PropelAuth returns the state parameter so you can confirm it matches with the one you generated before the request.
Name
prompt
Description
Optional: Set to login to force the user to login, regardless of if they have previously logged in already.
Name
org_id
Description
Optional: Allows you to specify which organization the user is logging in with. Subsequent access tokens will just be scoped to the provided organization.
Name
code_challenge
Description
*If using PKCE. The URL-safe base64 encoded sha256 hash of a random string.
Name
code_challenge_method
Description
*If using PKCE. Set to S256.

{AUTH_URL}/propelauth/oauth/authorize
    ?redirect_uri={REDIRECT_URI}
    &client_id={CLIENT_ID}
    &response_type=code
    &state={RANDOM_STRING}

POST{AUTH_URL}/propelauth/oauth/token

Token Endpoint

The token endpoint is used to generate an access token and refresh token. You can either exchange the code received from the Authorize Endpoint, or exchange an existing refresh token for a new access token and refresh token.

Request Headers

Name
Authorization
Type
Basic base64Encode(client_id:client_secret)
Description
Basic Auth where the username is your Client ID and the password is your Client Secret. *If using PKCE, do not include this header.
Name
Content-Type *
Type
application/x-www-form-urlencoded
Description

Request Body Parameters

Name
client_id *
Description
Found in the OAuth Config page.
Name
code *
Description
The code received from the Authorize Endpoint.
Name
redirect_uri *
Description
The provided URL must be set in the OAuth Config page.
Name
grant_type *
Description
Must be set to authorization_code.
Name
code_verifier
Description
*If using PKCE. The original secret created for the Authorize Endpoint.

curl --location --request POST '{AUTH_URL}/propelauth/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic MDk2N...' \
--data-urlencode 'client_id=0966..' \
--data-urlencode 'code=7KHj...' \
--data-urlencode 'redirect_uri=http://localhost:8000/oauth/authorize' \
--data-urlencode 'grant_type=authorization_code'

Successful Response

{
  "access_token": "eyJ0elb...",
  "token_type": "bearer",
  "expires_in": 1800,
  "refresh_token": "2c24f...",
  "id_token": "eyJ0e..."
}

POST{AUTH_URL}/propelauth/oauth/token

Refresh Token Endpoint

Request Headers

Name
Content-Type
Type
application/x-www-form-urlencoded
Description

Request Body Parameters

Name
client_id
Description
Found in the OAuth Config page.
Name
refresh_token
Description
The refresh token to exchange.
Name
grant_type
Description
Must be set to refresh_token.

Request

curl --location --request POST '{AUTH_URL}/propelauth/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=b2e7...' \
--data-urlencode 'client_id=0966...'

Successful Response

{
  "access_token": "eyJ0eXAiOi...",
  "refresh_token": "11a4a0fa...",
  "token_type": "bearer",
  "expires_in": 1800
}

GET{AUTH_URL}/propelauth/oauth/userinfo

User Info Endpoint

The userInfo endpoint is used to retrieve a user's information from PropelAuth. Use the access token generated by the Token Endpoint as a bearer token in the Authorization header.

Request Headers

Name
Authorization
Type
Bearer {accessToken}
Description

Request

curl --location --request GET '{AUTH_URL}/propelauth/oauth/userinfo' \
--header 'Authorization: Bearer {accessToken}'

Successful Response

{
    "can_create_orgs": true,
    "created_at": 1715092869,
    "email": "test@propelauth.com",
    "email_confirmed": true,
    "enabled": true,
    "first_name": "Test",
    "has_password": true,
    "last_active_at": 1716218560,
    "last_name": "Testing",
    "locked": false,
    "metadata": null,
    "mfa_enabled": false,
    "org_id_to_org_info": {},
    "picture_url": "https://img.propelauth.com/2a27...",
    "properties": {},
    "sub": "01702...",
    "update_password_required": false,
    "user_id": "01702..."
}

POST{AUTH_URL}/api/backend/v1/logout

Logout Endpoint

The logout endpoint will invalidate the refresh token and log the user out of the hosted UIs. This endpoint belongs to PropelAuth's backend API, so the request must come from your backend.

This endpoint may not be compatible with OAuth2 or OIDC libraries. If you have any questions about how to log users out, please reach out to support@propelauth.com

Request Headers

Name
Content-Type
Type
application/json
Description

Request Body Parameters

Name
refresh_token
Description
The refresh token to invalidate.

Request

curl --location --request POST '{AUTH_URL}/api/backend/v1/logout' \
--header 'Content-Type: application/json' \
--data '{"refresh_token": "11a458..."}'

Successful Response

200 OK

GET{AUTH_URL}/.well-known/openid-configuration

OpenID Connect Discovery Endpoint

Returns a JSON listing of the OpenID/OAuth endpoints, supported scopes and claims, and other details. Some OAuth2 and OpenID connect libraries can use this information to automatically construct requests to the PropelAuth OAuth2 API.

Request

curl --location --request GET '{AUTH_URL}/.well-known/openid-configuration'

Successful Response

{
    "authorization_endpoint": "{YOUR_AUTH_URL}/propelauth/oauth/authorize",
    "claims_supported": [
        "email",
        "exp",
        "first_name",
        "last_name",
        "iat",
        "iss",
        "picture_url"
    ],
    "code_challenge_methods_supported": [
        "S256"
    ],
    "grant_types_supported": [
        "authorization_code"
    ],
    "id_token_signing_alg_values_supported": [
        "RS256"
    ],
    "issuer": "{YOUR_AUTH_URL}",
    "jwks_uri": "{YOUR_AUTH_URL}/.well-known/jwks.json",
    "response_types_supported": [
        "code"
    ],
    "scopes_supported": [
        "openid",
        "email",
        "profile"
    ],
    "subject_types_supported": [
        "public"
    ],
    "token_endpoint": "{YOUR_AUTH_URL}/propelauth/oauth/token",
    "token_endpoint_auth_methods_supported": [
        "client_secret_basic"
    ],
    "userinfo_endpoint": "{YOUR_AUTH_URL}/propelauth/oauth/userinfo"
}