# 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](https://docs.propelauth.com/overview/authentication/oauth2).

---

GET{AUTH_URL}/propelauth/oauth/authorize

## [Authorize Endpoint](https://docs.propelauth.com/reference/api/oauth2?ref=propelauth.mymidnight.blog#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

```text
{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](https://docs.propelauth.com/reference/api/oauth2?ref=propelauth.mymidnight.blog#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](https://docs.propelauth.com/reference/api/oauth2?ref=propelauth.mymidnight.blog#authorize-endpoint), or [exchange an existing refresh token](https://docs.propelauth.com/reference/api/oauth2?ref=propelauth.mymidnight.blog#refresh-token-endpoint) 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](https://docs.propelauth.com/reference/api/oauth2?ref=propelauth.mymidnight.blog#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](https://docs.propelauth.com/reference/api/oauth2#authorize-endpoint).

StandardPKCE

```bash
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

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

---

POST{AUTH_URL}/propelauth/oauth/token

## [Refresh Token Endpoint](https://docs.propelauth.com/reference/api/oauth2?ref=propelauth.mymidnight.blog#refresh-token-endpoint)

The token endpoint is used to generate an access token and refresh token. You can either [exchange the code](https://docs.propelauth.com/reference/api/oauth2?ref=propelauth.mymidnight.blog#token-endpoint) received from the [Authorize Endpoint](https://docs.propelauth.com/reference/api/oauth2?ref=propelauth.mymidnight.blog#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

```bash
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

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

---

GET{AUTH_URL}/propelauth/oauth/userinfo

## [User Info Endpoint](https://docs.propelauth.com/reference/api/oauth2?ref=propelauth.mymidnight.blog#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](https://docs.propelauth.com/reference/api/oauth2#token-endpoint) as a bearer token in the Authorization header.

### Request Headers

- Name `Authorization` Type Bearer {accessToken} Description

### Request

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

### Successful Response

```bash
{
    "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](https://docs.propelauth.com/reference/api/oauth2?ref=propelauth.mymidnight.blog#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](mailto: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

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

### Successful Response

```bash
200 OK
```

---

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

## [OpenID Connect Discovery Endpoint](https://docs.propelauth.com/reference/api/oauth2?ref=propelauth.mymidnight.blog#open-id-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

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

### Successful Response

```bash
{
    "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"
}
```