Authentication and Authorization

Regular Web App

GET /connect/authorize?client_id=YOUR_CLIENT_ID&response_type=code&scope=readwrite%3Acore%20offline_access&redirect_uri=YOUR_REDIRECT_URI&state=STATE_VALUE

https://YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=STATE_VALUE

curl --request POST \
  --url /connect/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code' \
  --data 'redirect_uri=YOUR_REDIRECT_URI' \
  --data 'code=AUTHORIZATION_CODE' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET'

Web App (FAPI/PAR)

Web App (FAPI/PAR) is a high-security application type for server-side web applications that must use a hardened OAuth 2.0 pattern. It is designed for regulated or security-sensitive integrations and builds on the Regular Web App Authorization Code flow, with these key differences:

• The authorization request parameters are pushed to a backchannel Pushed Authorization Request (PAR) endpoint first, instead of being placed directly in the browser redirect query string.
• The browser redirect uses a short-lived request_uri reference returned by the PAR endpoint.
• PKCE is required, in addition to Client Secret.

Flow Summary

The Web App (FAPI/PAR) Authorization Code flow typically includes these steps:

1. Your server generates PKCE values (code_verifier and code_challenge).
2. Your server sends a Pushed Authorization Request (PAR) to CORE Authorization Server and receives a request_uri.
3. Your app redirects the user’s browser to the authorization endpoint using the request_uri.
4. CORE Authorization Server authenticates the user and shows the consent screen.
5. After the user grants consent, CORE Authorization Server redirects the user back to your redirect URI with an authorization code.
6. Your server exchanges the code for tokens at the token endpoint, sending the client_secret and code_verifier.

Endpoints used in the flow

Base URI:

Endpoints:

• PAR: POST /connect/par
• Authorization: GET /connect/authorize
• Token: POST /connect/token

Step 1: Generate PKCE values

Before you start the flow, your server must:

• Generate a code_verifier: a cryptographically random string (43–128 characters)
• Derive a code_challenge: Base64 URL-encoded SHA-256 hash of the code_verifier
• Set code_challenge_method to S256

Store the code_verifier securely on the server (for example, in the user’s session) until the token exchange step.

Step 2: Send the Pushed Authorization Request (PAR)

Unlike the Regular Web App flow, your server sends the authorization parameters to the PAR endpoint instead of sending authorization parameters directly to /connect/authorize in the browser.

Endpoint used

/connect/par

curl --request POST \
  --url /connect/par \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET' \
  --data 'response_type=code' \
  --data 'redirect_uri=YOUR_REDIRECT_URI' \
  --data 'scope=readwrite%3Acore%20offline_access' \
  --data 'state=STATE_VALUE' \
  --data 'code_challenge=YOUR_CODE_CHALLENGE' \
  --data 'code_challenge_method=S256'

PAR request parameters

A successful PAR response returns a short-lived request_uri value:

Save the full request_uri value and use it immediately in the redirect step. Do not treat it as a long-lived value.

Step 3: Redirect the user to the authorization endpoint

After receiving the request_uri, redirect the user’s browser to /connect/authorize using only the client_id and request_uri.

Endpoint used

/connect/authorize

GET ?client_id=YOUR_CLIENT_ID&request_uri=REQUEST_URI

Step 4: User Consent

From this point forward, the user experience is the same as the Regular Web App flow. For more details on this step, see Getting Started: Implement Authorization Code Flow.

1. Users see a secure CORE Log In screen where they need to enter their CORE company credentials.
2. After logging in, users see a consent screen showing requested permissions (scopes).
3. On the consent screen, users can click Grant Permission to grant the selected permissions to your app or Decline to refuse access.
4. If the users grant permission, the Authorization Server redirects them to your Redirect URI with an authorization code.

Step 5: Handle the redirect back to your app

If a user grants access to your app, the CORE Authorization Server redirects to your registered redirect_uri with a code and (if you provided it) state.

https://YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=STATE_VALUE

Your app must then:

• Extract code
• Verify that state matches the value you originally generated and stored

If the user declines consent, your app receives an error response at the redirect URI (error=access_denied).

Step 6: Exchange the authorization code for tokens

Your server exchanges the authorization code for tokens using the token endpoint. For Web App (FAPI/PAR), the token request must include:

• client_secret (confidential client)
• code_verifier (PKCE)

Endpoint used

/connect/token

curl --request POST \
  --url /connect/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code' \
  --data 'redirect_uri=YOUR_REDIRECT_URI' \
  --data 'code=AUTHORIZATION_CODE' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET' \
  --data 'code_verifier=YOUR_CODE_VERIFIER'

Token request parameters

The response contains an access_token. If the user granted offline_access, the response also includes a refresh_token.

Common Errors and Troubleshooting

PAR request fails immediately

Common causes:

• Invalid client credentials (invalid_client)
• Missing required parameter (invalid_request)
• Redirect URI mismatch
• Scope not valid (invalid_scope)

Authorization redirect fails

Common causes:

• Expired or invalid request_uri
• Wrong (client_id)
• Attempting to reuse a (request_uri)

Token exchange fails

Common causes:

• Wrong or reused authorization code (invalid_grant)
• Redirect URI mismatch
• Missing or incorrect code_verifier
• Invalid client_secret

Security Notes

• Store client_secret and code_verifier on the server only.
• Always use and validate state to mitigate CSRF.
• Use short-lived sessions for pending authorization requests and clear them after the token exchange.