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

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

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