Skip to main content

Integration with Authentication REST API

This guide shows you how to set up an integration with Personalausweis, using the Signicat Authentication REST API with redirect flow.

Prerequisites​

  1. Follow the steps on the Configure Personalausweis page to establish a connection with Personalausweis.

  2. Before you can start making requests to the Authentication REST API, you need to learn how to connect to it. To do this, see Connect to Signicat APIs Quick start guide.

    Want to learn more?

    To learn more about the Signicat Authentication REST API, see:

Redirect flow​

This section details how to set up authentication for Personalausweis using the redirect flow. The redirect flow allows you to pass an authorization URL to your end-users that they can open in a browser to follow an identity verification flow with Personalausweis.

Create a session​

Request​

To create a session using the Authentication REST API, send a POST request to https://api.signicat.com/auth/rest/sessions.

For example, include the following fields in the payload:

{
    "allowedProviders": [
        "npa"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "firstName",
        "lastName",
        "name",
        "dateOfBirth",
        "placeOfBirth",
        "academicTitle",
        "documentType",
        "issuingState",
        "dateOfExpiry",
        "address"
	],
    "callbackUrls": {
        "success": "https://example.com/success",
        "abort": "https://example.com/abort",
        "error": "https://example.com/error"
	}
}

Note the following fields in the payload of the request:

For more information about the "Create a session" endpoint, see the API Reference description.

Response​

After you create a session, you receive a response with a summary of your request, a unique ID for the process and an authenticationUrl.

Here is an example response:

{
    "id": "c99e17e2-b124-f549-a88c-408f8e555d31",
    "accountId": "<YOUR_SIGNICAT_ACCOUNT_ID>",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=fdc41240-9703-af4e-941e-f6a6a7a540f9&transactionId=c99e17e2-b124-f549-a88c-408f8e555d31",
    "status": "CREATED",
    "callbackUrls": {
        "success": "https://example.com/success?sessionId=c99e17e2-b124-f549-a88c-408f8e555d31",
        "abort": "https://example.com/abort?sessionId=c99e17e2-b124-f549-a88c-408f8e555d31",
        "error": "https://example.com/error?sessionId=c99e17e2-b124-f549-a88c-408f8e555d31"
    },
    "allowedProviders": [
        "npa"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "idpId",
        "firstName",
        "lastName",
        "name",
        "dateOfBirth",
        "placeOfBirth",
        "academicTitle",
        "documentType",
        "issuingState",
        "dateOfExpiry",
        "address"
    ],
    "sessionLifetime": 1200,
    "expiresAt": "2024-06-11T07:56:36.587157+00:00"
}

Use the response​

Now, your application can redirect the end-user to the authenticationUrl you obtained in the response. This is a unique URL that allows the end-user to perform authentication in the context of the session you just created.

User journey​

At the authentication URL, end-users follow an authentication flow with Personalausweis. You can preview what the flow looks like in the Use cases and flows page.

When the end-user completes the authentication flow, they are automatically redirected to the callbackUrls according to the outcome of the authentication.

Get the session status​

During the authentication process, you can monitor the status of the session to track whether the flow has started, failed or completed. Responses from successful authentications contain the end-user personal data.

Request​

To get the status of a session, send a GET request to https://api.signicat.com/auth/rest/sessions/{id}. You can find the id value in the response you received when you created the session. No data specific to Personalausweis needs to be included in this request.

In the response example above, the id is c99e17e2-b124-f549-a88c-408f8e555d31 so the request would be https://api.signicat.com/auth/rest/sessions/c99e17e2-b124-f549-a88c-408f8e555d31.

Response​

The response contains a status field, which you can use to monitor the current status of the session. For example, the response of a successful session is:


{
    "id": "c99e17e2-b124-f549-a88c-408f8e555d31",
    "accountId": "<YOUR_SIGNICAT_ACCOUNT_ID>",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=fdc41240-9703-af4e-941e-f6a6a7a540f9",
    "status": "SUCCESS",
    "provider": "npa",
    ...
}
Status overview​

The status field could contain one of the following values:

For more information about the "Get session status" endpoint, see the API Reference description.

Use the response​

If the returned status is SUCCESS, the JSON object in the subject field of the response contains information about the authenticated end-user. For example:

{
    "id": "c99e17e2-b124-f549-a88c-408f8e555d31",
    "accountId": "<YOUR_SIGNICAT_ACCOUNT_ID>",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=fdc41240-9703-af4e-941e-f6a6a7a540f9&transactionId=c99e17e2-b124-f549-a88c-408f8e555d31",
    "status": "SUCCESS",
    "provider": "npa",
    "subject": {
        "id": "X6hYgXvTvNMf27-mC0cYzOUb4HBWR1feCSh5Ul7KiNQ=",
        "idpId": "5D6C804FC44BEEDA94265B8CFC1B5D120DC6EBE949D8690DAF515D0D4163066F",
        "firstName": "Hans-Günther",
        "lastName": "von Drebenbusch-Dalgoßen",
        "name": "Hans-Günther von Drebenbusch-Dalgoßen",
        "dateOfBirth": "1946-01-25",
        "placeOfBirth": "BREMERHAVEN",
        "academicTitle": "Dr.eh.Dr.",
        "documentType": "ID",
        "issuingState": "D",
        "dateOfExpiry": "2027-04-05",
        "address": "WEG NR. 12 8E, 22043, HAMBURG, D",
        "addressFormatted": {
            "FullAddress": "WEG NR. 12 8E, 22043, HAMBURG, D",
            "Street": "WEG NR. 12 8E",
            "City": "HAMBURG",
            "PostalCode": "22043",
            "Country": "D"
        }
    },
    "callbackUrls": {
        "success": "https://example.com/success?sessionId=c99e17e2-b124-f549-a88c-408f8e555d31",
        "abort": "https://example.com/abort?sessionId=c99e17e2-b124-f549-a88c-408f8e555d31",
        "error": "https://example.com/error?sessionId=c99e17e2-b124-f549-a88c-408f8e555d31"
    },
    "environment": {
        "ipAddress": "192.0.2.2",
        "userAgent": "Mozilla/5.0 (X11; Linux x86_64; rv:126.0) Gecko/20100101 Firefox/126.0"
    },
    "allowedProviders": [
        "npa"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "idpId",
        "firstName",
        "lastName",
        "name",
        "dateOfBirth",
        "placeOfBirth",
        "academicTitle",
        "documentType",
        "issuingState",
        "dateOfExpiry",
        "address"
    ],
    "sessionLifetime": 1200,
    "expiresAt": "2024-06-11T07:56:36.587157+00:00"
}

In the response object, you can also see the identity provider specified in the provider field. This can be useful if you specified more than one provider when you created the session.

Success!

You have now completed an identity verification flow with Personalausweis using the Signicat Authentication REST API.

Next steps​

Continue your journey with more Personalausweis guides:

Attributes reference
Attributes reference and data for Personalausweis
Go to production
Connect to Personalausweis in a production account

Dive deeper into the Signicat Authentication REST API:

Authentication REST API documentation
Find out more about the Signicat Authentication REST API.
Authentication REST API reference
Discover the endpoints of the Authentication REST API
On this page