3. Token Endpoint
The Token Endpoint is used by the client to exchange an authorization code for tokens after the user successfully authenticates. This is a secure back-channel request made directly between the client and Corppass.
Returned Tokens
ID Token: A signed and encrypted JWE that includes the entity and user information. Relying Parties (RPs) must decrypt it using their private encryption key, then verify the JWT's signature using Corppass' public keys, available at the Corppass JWKS endpoint.
Access Token: A signed JWS intended for the Corppass resource server(s).
Supported Grant Types
Grant types define the method by which a client obtains tokens from the authorization server.
For the Open ID Connect (OIDC) authentication flow, Corppass supports the following grant types:
authorization_code
Used to securely exchange an authorization code for an ID token and Access Token. Requires prior user authentication and is suitable for confidential clients.
Refer to Section 3.1 of the OIDC Core Specification for more details.
Request
To obtain the Access Token and ID Token, send a POST request to the Token Endpoint URL obtained from the OpenID Discovery Endpoint (token_endpoint).
POST /mga/sps/oauth/oauth20/tokenRequest Headers
Content-Type
Yes
Indicates the encoding format of the request body.
Validation:
Must be set to
application/x-www-form-urlencoded.
DPoP
Yes
DPoP Proof JWT. A distinct JSON Web Token (JWT) that proves the client possesses the private key corresponding to the public key used for token binding.
Validation:
Must be signed using the exact same private key as the DPoP proof presented in the Pushed Authorization Request (PAR) step.
Refer to the Demonstrating Proof of Possession section for more details.
Request Body
code
Yes
Authorization Code. The authorization code issued during the callback step at Authorization Endpoint.
Validation:
The code is valid for 60 seconds. Expired codes will result in an error.
The code can only be exchanged once.
redirect_uri
Yes
The absolute URI used in the initial authorization request (PAR).
Validation:
Must strictly match the
redirect_uriprovided in the original Pushed Authorization Request (PAR).
grant_type
Yes
The type of authorization grant being requested.
Validation:
Must be set to
authorization_code.
client_id
No
Optional. The unique identifier assigned to the Relying Party during onboarding.
Validation:
If provided, this value must match the
sub(subject) claim in the Client Assertion JWT.
client_assertion_type
Yes
Specifies the format of the client assertion.
Validation:
Must be set to
urn:ietf:params:oauth:client-assertion-type:jwt-bearer, as mandated by OIDC specifications.
client_assertion
Yes
A signed JWT used to authenticate the client application.
Validation:
Must be generated afresh for each authorization session.
Must contain a unique
jti(JWT ID) claim to prevent replay attacks.Must be signed using the Private Key corresponding to the public key registered in your JWKS.
Refer to Client Assertion JWT section for more details.
code_verifier
Yes
PKCE Verifier. The cryptographically random string generated by the client to prove possession of the code_challenge.
Validation:
Must be the original plain-text value used to generate the
code_challengeprovided at PAR.
Refer to Proof Key of Code Exchange for more details.
Sample Request
Success Response
If the request is valid, Corppass returns a JSON response containing the tokens.
Response Body
access_token
JWS
Access Token. A signed JSON Web Signature (JWS) used to access protected resources (e.g., Userinfo Endpoint).
The token is valid for 10 minutes from time of issuance.
Refer to the Access Token section for more details.
id_token
JWE
ID Token. A signed and encrypted JSON Web Encryption (JWE) containing user and entity identities, and authentication claims.
Processing:
The RP must decrypt this token using their Private Encryption Key.
After decryption, the inner JWT signature must be verified using Corppass' public keys.
Refer to the ID Token section for more details.
token_type
String
Indicates the type of access token issued.
Value is always set to DPoP.
expires_in
Numeric
The remaining lifetime of the Access Token in seconds.
Value is set to 600 seconds.
scope
String
Granted Scopes. A space-delimited list of scopes actually granted to the Access Token.
This list typically matches the scopes requested during authorization, though the server may grant a subset of requested scopes based on user consent or policy.
Sample Response
Error Response
If the token exchange fails, Corppass returns a JSON response containing an error code and description.
Response Body
error
String
A standardised error code identifying the type of error that occurred.
See Error Codes below for a complete list of possible values.
error_description
String
A human-readable text description providing additional details about the error.
Error Codes
invalid_request
400 / 401
The request is missing a required parameter, includes an unsupported or duplicated parameter, or is malformed.
invalid_client
400 / 401
Client authentication failed due to a missing, invalid, expired, or improperly formatted client credential or assertion.
invalid_grant
400 / 401
The provided authorization code is invalid, expired, revoked, or does not match the authenticated client.
invalid_dpop_proof
401
The DPoP proof is invalid, expired, malformed, or failed verification.
unsupported_grant_type
400
The grant type is not supported.
server_error
500
The authorization server encountered an unexpected internal error while processing the request. The error can potentially be due to the RP’s JWK endpoint being unreachable or returning a malformed JWK.
temporarily_unavailable
503
The server is temporarily unable to handle the request due to maintenance or high load.
Sample Response
Next Steps
1. Retrieve Entity & User Identity (ID Token)
The ID Token contains information about both the Entity and the Acting User performing the transaction.
Proceed to ID Token section for decryption steps and claim mapping.
2. Fetch Additional Data (Userinfo Endpoint)
If your application requires more detailed entity and user attributes not present in the ID Token, use the Access Token to query the Userinfo Endpoint for additional information.
Proceed to 4. Userinfo Endpoint to fetch additional data.
Last updated