Implement with the Signicat REST API
This guide shows you how to authenticate end-users with ID Austria, using the Signicat Authentication REST API with redirect flow.
To learn more about the Signicat Authentication REST API before integrating, see:
- Authentication REST API documentation.
- API Reference for endpoint descriptions.
Prerequisites
- Follow the steps to Configure ID Austria services.
-
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.
Ensure that you set the Authentication REST API permission for your API client. When you have obtained an access token and are ready to make an API request, return here to resume this guide.
Learn more about the Signicat Authentication REST API- Authentication REST API for conceptual documentation.
- API Reference for endpoint descriptions.
Redirect flow
This guide shows how to set up authentication 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 ID Austria.
1. Create a session
Request
To create a session using the Authentication REST API, you need to send a POST request to the Create a new session endpoint.
Enpoint URL: https://api.signicat.com/auth/rest/sessions
For example, you can build your request like this:
POST /auth/rest/sessions HTTP/1.1
Host: api.signicat.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer <ACCESS_TOKEN>
Content-Length: 535
{
"flow": "redirect",
"requestedAttributes": [
"idpId",
"firstName",
"lastName",
"dateOfBirth",
"picture",
"gender",
"nationality",
"address",
"maritalStatus",
"nin",
],
"additionalParameters": {
"idaustria_service_id": "<YOUR_SERVICE_UUID>"
},
"callbackUrls": {
"success": "https://example.com/success",
"abort": "https://example.com/abort",
"error": "https://example.com/error"
},
"allowedProviders": [
"idaustria"
],
"language": "en"
}
Note the following fields in the payload of the request:
For more information about the "Create a new session" endpoint, see the API Reference description.
When you register a service in the Signicat Dashboard, the service is assigned a unique identifier, a UUID code.
You can override your default ID Austria service for a single authentication request. To do this, pass the service's UUID using the additionalParameters:
"additionalParameters": {
"idaustria_service_id": "<YOUR_SERVICE_UUID>"
}
This change only applies to the current transaction.
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": [
"idaustria"
],
"language": "en",
"flow": "redirect",
"requestedAttributes": [
"idpId",
"firstName",
"lastName",
"dateOfBirth",
"gender",
"picture",
"nationality",
"address",
"maritalStatus",
"nin",
],
"additionalParameters": {
"idaustria_service_id": "<YOUR_SERVICE_UUID>"
},
"sessionLifetime": 1200,
"expiresAt": "2026-04-30T12:43:22.0805822+00:00"
}
2. End-user authentication
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
By opening the authentication URL in the browser, end-users can follow an authentication flow with ID Austria.
When the end-user completes the authentication flow, they are automatically redirected to the callbackUrls according to the outcome of the authentication.
Test an authentication
To test an authentication flow during the implementation phase, you can use the test user credentials available in the Try it out page.
3. 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, you need to send a GET request to the Get session status endpoint.
You can find the session id value in the response you received when you created the session.
GET /auth/rest/sessions/{SESSION_ID} HTTP/1.1
Host: api.signicat.com
Accept: application/json
Authorization: Bearer <ACCESS_TOKEN>
In the response example above, substitute the SESSION_ID with the value of the id you received in the response after creating the session. The value of 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 with up-to-date information about the status of a session. Depending on the outcome of an authentication, the session can be in any of these states: CREATED, SUCCESS, ERROR, ABORT, CANCELLED, WAITING_FOR_USER, EXPIRED, INVALID. For more information about the "Get session status" endpoint, see the API Reference description.
Review the response
When the end-user authenticates successfully, you receive a response with status: SUCCESS. Then, you can retrieve personal data of the user in the subject field of the JSON response. 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": "idaustria",
"subject": {
"id": "qyIsCvjlb-UQAjOaH2JJXFXtZj4eXECrTrsexxpBOEI=",
"idpId": "https://idp.ref.id-austria.gv.at",
"name": "XXXClaus - Maria XXXvon Brandenburg",
"firstName": "XXXClaus - Maria",
"lastName": "XXXvon Brandenburg",
"dateOfBirth": "1994-12-31",
"gender": "M",
"picture": "/9j/4AAQSkZJRgABAQEBLAEsAAD/4gxAAAD/2Q==",
"nationality": "[\"AUT\",\"DEU\",\"CHE\"]",
"address": "Testgasse, 1a-2b, Testort A, 0088",
"addressFormatted":
{
"FullAddress": "Testgasse, 1a-2b, Testort A, 0088",
"Street": "Testgasse 1a-2b",
"HouseNumber": "1a-2b",
"City": "Testort A",
"PostalCode": "0088",
"Country": "AT"
},
"nin":
{
"value": "urn:publicid:gv.at:wbpk+XERSB+9110037664968",
"issuingCountry": "AT",
"type": "BPK"
},
"maritalStatus": "verheiratet",
},
"callbackUrls": {
"success": "https://example.com:443/success?sessionId=2cd8f5c5-468c-44d9-80ae-9dcfc8b10ea4",
"abort": "https://example.com:443/abort?sessionId=2cd8f5c5-468c-44d9-80ae-9dcfc8b10ea4",
"error": "https://example.com:443/error?sessionId=2cd8f5c5-468c-44d9-80ae-9dcfc8b10ea4"
},
"environment": {
"ipAddress": "192.0.2.0",
"userAgent": "userAgent"
},
"loa": "high",
"allowedProviders": [
"idaustria"
],
"language": "en",
"flow": "redirect",
"requestedAttributes": [
"idpId",
"firstName",
"lastName",
"dateOfBirth",
"gender",
"picture",
"nationality",
"address",
"maritalStatus",
"nin",
],
"additionalParameters": {
"idaustria_service_id": "<YOUR_SERVICE_UUID>"
},
"sessionLifetime": 1200,
"expiresAt": "2026-04-30T13:15:01.9071912+00:00"
}
In the response object, you also find the eID (see provider) that the end-user chose for authentication. This can be useful when more than one eID is active in your Signicat account.
You have now completed an authentication flow with ID Austria using the Signicat Authentication REST API.
UX considerations
To use the ID Austria buttons, badges, logos and other graphic elements correctly in your applications, you can download the ID Austria logo package and guide. For more information, visit the ID Austria website.
Next steps
Continue your journey with more ID Austria guides:
Dive deeper into the Signicat Authentication REST API: