OAuth2 API Reference - PropelAuth Docs

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: Can be set to any of the following:
- login: Always force the user to go through the login flow
- none: Prevent the login page from being shown. If the user is not already logged in, an error will be returned.
- select_account: Default behavior.
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.
Name signup Description Set to true if you want to redirect to your signup page.

StandardPKCE

{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.

StandardPKCE

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": {
        "example": "data"
    },
    "mfa_enabled": false,
    "org_id_to_org_info": {
        "92d47d6e-5ae7-42c4-ab3f-97a46c550011": {
            "additional_roles": [],
            "inherited_user_roles_plus_current_role": [
                "Owner",
                "Admin",
                "Member"
            ],
            "org_id": "92d47d6e-5ae7-42c4-ab3f-97a46c550011",
            "org_metadata": {
                "customKey": "customValue"
            },
            "org_name": "Acme Inc",
            "org_role_structure": "single_role_in_hierarchy",
            "url_safe_org_name": "acme-inc",
            "user_permissions": [
                "propelauth::can_invite"
            ],
            "user_role": "Owner"
        }
    },
    "picture_url": "https://img.propelauth.com/2a27...",
    "properties": {
        "favoriteSport": "Basketball",
        "metadata": {
            "example": "data"
        }
    },
    "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"
}