Logo

MCP Authentication API Reference

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

GET{AUTH_URL}/oauth/2.1/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 when creating the client in the MCP page.

  • Name
    client_id *
    Description

    Found in the MCP page under OAuth Clients.

  • 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
    code_challenge *
    Description

    The URL-safe base64 encoded sha256 hash of a random string.

  • Name
    code_challenge_method *
    Description

    Set to S256.

  • Name
    resource *
    Description

    The resource server to request access to. This is the URL of your MCP server.

  • Name
    scope
    Description

    Any scopes to request from the user. These must be set in the Scopes section of the MCP page

{AUTH_URL}/oauth/2.1/authorize
    ?redirect_uri={REDIRECT_URI}
    &client_id={CLIENT_ID}
    &response_type=code
    &state={RANDOM_STRING}
    &code_challenge={CODE_CHALLENGE}
    &code_challenge_method=S256
    &scope={SCOPES} //read:user_data+tools:execute
    &resource={RESOURCE_SERVER_URL}
POST{AUTH_URL}/oauth/2.1/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
    Content-Type *
    Type
    application/x-www-form-urlencoded
    Description

Request Body Parameters

  • Name
    client_id *
    Description

    Found in the MCP page under OAuth Clients.

  • Name
    code *
    Description

    The code received from the Authorize Endpoint.

  • Name
    redirect_uri *
    Description

    The URL where the user is directed to after a successful login. The provided URL must be set when creating the client in the MCP page.

  • Name
    grant_type *
    Description

    Must be set to authorization_code.

  • Name
    code_verifier *
    Description

    The original secret created for the Authorize Endpoint.

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

Successful Response

{
    "access_token": "28bdcd0d0d37761242...",
    "refresh_token": "c87981a37bd834c86...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "read:user_data"
}
POST{AUTH_URL}/oauth/2.1/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 MCP page under OAuth Clients.

  • Name
    client_secret *
    Description

    Found when creating a new OAuth Client in the MCP 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}/oauth/2.1/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...' \
--data-urlencode 'client_secret=0966...'

Successful Response

{
    "access_token": "80becb83aae...",
    "refresh_token": "ba58982483...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "read:user_data"
}
POST{AUTH_URL}/oauth/2.1/introspect

Introspection Endpoint

The introspection endpoint is used to validate an access token and retrieve a user's information and scopes from PropelAuth. Use the access token generated by the Token Endpoint in the request body.

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. These are not the Client ID and Client Secret from your MCP Client. Get your Client ID and Client Secret for this API from the Request Validation section of the MCP page in the PropelAuth Dashboard.

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

Request

curl --location --request POST '{AUTH_URL}oauth/2.1/introspect' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic MDk2N...' \
--data-urlencode 'token=0966..'

Successful Response

{
    "active": true,
    "client_id": "016444257691d40192fb975819f937eb",
    "username": "user@acmeinc.com",
    "scope": "read:user_data",
    "sub": "667da91e-ae08-4056-93fb-24f6768e1205",
    "aud": "https://myserver.com/mcp",
    "iss": "{AUTH_URL}",
    "exp": 1768521751,
    "iat": 1768518151
}
POST{AUTH_URL}/oauth/2.1/register

Registration Endpoint

Allows for Dynamic Client Registration with services that allow for it. Dynamic Client Registration must be enabled in order for this endpoint to be available.

Request Headers

  • Name
    Content-Type
    Type
    application/json
    Description

Request Body Parameters

  • Name
    redirect_uris *
    Description

    An array of redirect URIs. The redirect URIs must be set as allowed in the Allowed MCP Clients section of the MCP page.

  • Name
    client_name
    Description

    The name of the client.

  • Name
    client_uri
    Description

    The URL of the client.

  • Name
    response_types
    Description

    An array of response types. This must be set to code.

  • Name
    grant_types
    Description

    An array of grant types. Supported types include authorization_code and refresh_token.

  • Name
    token_endpoint_auth_method
    Description

    The supported token endpoint authentication method. Supported types include client_secret_basic, client_secret_post, and none.

Request

curl --location --request POST '{AUTH_URL}/oauth/2.1/register' \
--header 'Content-Type: application/json' \
--data '{
    "redirect_uris": ["http://localhost:3000/callback"],
    "client_name": "Example Client",
    "client_uri": "https://example.com",
    "response_types": ["code"],
    "grant_types": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_method": "client_secret_basic"
}'

Successful Response

{
    "client_id": "39f2400826394a2b3df76870236b5992",
    "client_secret": "39f2400826394a2b3df7...",
    "client_secret_expires_at": 0,
    "client_name": "Example Client",
    "client_uri": "https://example.com",
    "redirect_uris": [
        "http://localhost:3000/callback"
    ],
    "response_types": [
        "code"
    ],
    "grant_types": [
        "authorization_code",
        "refresh_token"
    ],
    "token_endpoint_auth_method": "client_secret_basic"
}
GET{AUTH_URL}/.well-known/oauth-authorization-server/oauth/2.1

Authorization Server Discovery Endpoint

Returns a JSON listing of the OAuth endpoints, supported scopes and claims, and other details. Some MCP services can use this information to automatically construct requests to the PropelAuth MCP Client API.

Request

curl --location --request GET '{AUTH_URL}/.well-known/oauth-authorization-server/oauth/2.1'

Successful Response

{
    "authorization_endpoint":"{AUTH_URL}/oauth/2.1/authorize",
    "code_challenge_methods_supported":["S256"],
    "grant_types_supported":["authorization_code","refresh_token"],
    "introspection_endpoint":"{AUTH_URL}/oauth/2.1/introspect",
    "issuer":"{AUTH_URL}",
    "registration_endpoint":"{AUTH_URL}/oauth/2.1/register",
    "response_types_supported":["code"],
    "scopes_supported":["read:user_data","tools:execute","google_calendar:read"],
    "token_endpoint":"{AUTH_URL}/oauth/2.1/token",
    "token_endpoint_auth_methods_supported":["client_secret_basic","client_secret_post","none"]
}