Migrating from Express
For the Signicat Digital Trust Platform (DTP), we have made the Signicat Authentication REST API more tightly integrated with the platform to take full advantage of its possibilities. However, we have taken care to make the migration from the old API in Express as seamless as possible.
Key differences
- Authorization: DTP does not use the same access and identity and access management (IAM) control as Express.
- Endpoints: The general flow is the same, but with minor differences.
- Data models: The request and response objects have slightly different structures.
- Encrypted responses: DTP does not sign encrypted responses.
In addition, there are some general differences between Express and DTP; the concept of organisations and accounts, eIDs, platform differences, etc. You can find more information about these concepts in the General information section.
Authorization
Signicat DTP features a richer and more powerful access and IAM control. Although technically different, it is practically similar as it is still using an OAuth2 client credentials flow.
The executive summary is that you will use a new token URL, a new client (client ID and client secret) and a different scope.
For more information on how to authorize, see Accessing Signicat API products.
Endpoints
We have made some minor changes to our endpoints, but the general structure remains much the same.
| Name | Endpoint | Change |
|---|---|---|
| Create session | POST /sessions | New parameter, signicat-accountId. |
| Retrieve session | GET /sessions/{id} | New parameter, signicat-accountId. |
| List sessions | GET /sessions/{id} | This endpoint has been deprecated. |
| Invalidate session | GET /sessions/{id} | This endpoint has been deprecated. |
"List sessions" and "Invalidate session" have been deprecated because of a different way of treating non-permanent data in DTP. When a session expires in DTP (with sessionLifetime), it's completely deleted from our system. It's done this way to increase protection of PII and simplify data management.
Data models
We have improved the structure of the request and response objects to make them clearer and more concise.
Request
| Old name (Express) | New name (DTP) | Comment |
|---|---|---|
allowedProviders | allowedProviders | Same field name, but new values: ["nbid", "sbid"]. |
include | requestedAttributes | New field name and new values (see API specification for details). |
redirectSettings | CallbackUrls | New field name and new values: ["success", "abort", "error"]. |
| - | sessionLifetime | New field (not required). |
| - | themeId | New field (not required). |
Response
| Old Name (Express) | New Name (DTP) | Comment |
|---|---|---|
url | authenticationUrl | New field name, but the same purpose. |
status | status | Same field name, but values are capitalized. |
identity | subject | New field name and new values: (see API specification for details). |
identity.providerId | subject.idpId | New field name, but the same purpose. Field representing the user's unique ID from the eID provider. |
Encrypted responses
Although it is possible to encrypt the response you receive from Signicat, DTP does not sign the response (with a digital signature). This means that you only need to decrypt the response, as explained in Encrypted responses from Signicat page.