Verify Service Provider (2.0.0)

Download OpenAPI specification:Download

This is a description of the API for the Verify Service Provider.

The API allows you to generate a SAML authentication request and to translate a SAML response into JSON. To use the Verify Service Provider, you must download your own version.

If you are using the legacy setup involving a Matching Service Adapter, see the API documentation for the legacy setup.

Generate a SAML authentication request

Generate a SAML authentication request, known as an AuthnRequest, to send to Verify Hub.

See the GOV.UK Verify technical documentation for more information on how to generate an authentication request.

Request Body schema: application/json
entityId
string (EntityId)

The EntityId for the service interacting with the Verify Service Provider. This is required if there is more than one service connected to the same Verify Service Provider deployment, otherwise it is optional. The value, if provided, must be one of those listed in the configuration for the Verify Service Provider.

Responses

200

Contains an object with a valid SAML authentication request that can be consumed by the GOV.UK Verify Hub.

422

An error due to a JSON request in an invalid format, for example missing required parameters.

500

An error due to an internal server error.

post /generate-request
/generate-request

Request samples

application/json
Copy
Expand all Collapse all
{
  • "entityId": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "samlRequest": "string",
  • "requestId": "string",
  • "ssoLocation": "string"
}

Translate a SAML response

Translate a SAML response received from the GOV.UK Verify Hub into JSON.

See the GOV.UK Verify technical documentation for more information on how to handle the response

Request Body schema: application/json

An object containing the SAML response returned by the GOV.UK Verify Hub.

samlResponse
required
string <byte>

A SAML response as a base64 encoded string.

requestId
required
string <byte>

A token that was generated for the original SAML authentication request. This is used to verify that the SAML authentication request and SAML response have passed through the same browser.

levelOfAssurance
required
string (RequiredLevelOfAssurance)
Enum:"LEVEL_1" "LEVEL_2" "LEVEL_3" "LEVEL_4"

The minimum level of assurance required by the service.

Responses

200

Contains the details of the SAML response, translated into JSON.

400

An error due to a problem with translating the response.

422

An error due to a JSON request in an invalid format, for example missing required parameters.

500

An error due to an internal server error.

post /translate-response
/translate-response

Request samples

application/json
Copy
Expand all Collapse all
{
  • "samlResponse": "string",
  • "requestId": "string",
  • "levelOfAssurance": "LEVEL_1"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "scenario": "IDENTITY_VERIFIED",
  • "pid": "string",
  • "levelOfAssurance": "LEVEL_1",
  • "attributes":
    {
    }
}