Consent Endpoint

The Consent endpoint allows verifying the status of the user's consent to share their data with the client application and, if required, prompt the user to sign (for example, if the consent is not signed, has expired or been updated).

The returned consent content that the user is prompted to sign is based on the scopes requested in the authorization request and must be allowed by the OpenID client configuration.

The consent information can be accessed (Retrieve and Update) once the user is authenticated via the Code endpoint.

The consent can be customized (labels and description) as described in Customizing the Consent Display.

Copy

The endpoint is exposed at the following URL (and can be obtained from the server discovery endpoint):

https://[base-server-url]/{tenant}/authn/consent [GET]/[PUT]

Method Details

GET

PUT

Retrieve Consent

Copy

Sample request

GET https://[base-server-url]/{tenant}/authn/consent?request_uri=urn%3Ahid%3A256ab6ef-12c4-47e3-b220-0e96c161d283&username=spl-cust01 HTTP/1.1
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283

Copy

Sample response

HTTP/1.1 200 OK
Content-Type: application/json
server-csrf-token: urn:hid:60419bb3-2ab3-47ac-a767-334eb0aeacb5
Cache-Control: no-store
Pragma: no-cache
{
    "consents": [{
        "clientid": "spl-api",
        "sharing_duration": 0,
        "sharings": [
            {
                "scope": "openid",
                "description": "Openid standard scope",
                "status": "unknown",
            },
            {
                "scope": "profile",
                "description": "User profile information like email address and phone number",
                "status": "unknown"
            }
        ]
    }]
}

Update Consent

Copy

Sample request with user signature of the consent

PUT https://[base-server-url]/{tenant}/authn/consent HTTP/1.1
Content-Type: application/x-www-form-urlencoded
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
request_uri=urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
&username=spl-cust01
&sharings=[
    {
        "scope":"openid",
        "status":"accepted",
        "exp":60000
    },
    {
        "scope":"profile",
        "status":"accepted",
        "exp":60000
    }
]

Copy

Sample response

HTTP/1.1 200 OK
Content-Type: application/json 
server-csrf-token: urn:hid:60419bb3-2ab3-47ac-a767-334eb0aeacb5
Cache-Control: no-store
Pragma: no-cache
{
    "consents": [
        {
            "clientid": "spl-api",
            "sharing_duration": 60000,
            "sharings": [
                {
                    "scope": "openid",
                    "description": "Openid standard scope",
                    "status": "accepted"
                },
                {
                    "scope": "profile",
                    "description": "User profile information like email address and phone number",
                    "status": "accepted"
                }
            ]
        }
    ]
}

Copy

Sample request with the user's denial of the consent

PUT https://[base-server-url]/{tenant}/authn/consent HTTP/1.1
Content-Type: application/x-www-form-urlencoded 
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
request_uri=urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
&username=spl-cust01
&sharings=[
    {
        "scope":"openid",
        "status":"denied"
    },
    {
        "scope":"profile",
        "status":"denied"
    }
]

Copy

Sample response with the consent denied status

HTTP/1.1 200 OK
Content-Type: application/json
server-csrf-token: urn:hid:60419bb3-2ab3-47ac-a767-334eb0aeacb5
Cache-Control: no-store
Pragma: no-cache
{
    "consents": [
        {
            "clientid": "spl-api",
            "sharing_duration": 0,
            "sharings": [
                {
                    "scope": "openid",
                    "description": "Openid standard scope",
                    "status": "denied"
                },
                {
                    "scope": "profile",
                    "description": "User profile information like email address and phone number",
                    "status": "denied"
                }
            ]
        }
    ]
}

Once the consent is denied, the requests will fail and calls to all APIs will return errors except POST /code and GET /code.

Supported Parameters

The Retrieve and Update methods support the following parameters:

Paremeter	Description
sharing_duration	Duration period (in milliseconds) for which the consent for all scopes is shared with the client application If set to -1, the sharing duration never expires.
exp	Duration period (in milliseconds) for which the consent of the specific scope is shared with the client application If absent, the sharing duration never expires.
status	Status of the user's consent Possible values are: unknown - consent is not signed or has expired accepted - consent is signed and valid denied - user has refused their consent to share their data with the client application This is only used by PUT where the denied consent can invoke the authentication failure
description	Description of the scope as defined in the OpenID client configuration. If it the description is not defined, the scope name will be used (for example, profile).

Error Responses

Code	Label	Possible Errors
400	BAD REQUEST	invalid_request
403	FORBIDDEN	access_denied

Copy

User is not authenticated

HTTP/1.1 403 Forbidden
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "error_description": "Access denied by resource owner or authorization server : End user not authenticated",
    "error": "access_denied"
}