Nedan är vår API-beskrivning för GRP3 (REST). Kontakta oss via funktionstjanster@cgi.com vid önskemål om SOAP (Legacy) dokumentation.

1 General info
- 1.1 Auth/Sign
- 1.2 Request:
  - 1.2.1 Query parameters:
- 1.3 Body:
  - 1.3.1 Request body example:
- 1.4 Response:
  - 1.4.1 Successful auth attempt started response example:
- 1.5 Collect
- 1.6 Request:
- 1.7 Response:
  - 1.7.1 In progress auth attempt response example:
  - 1.7.2 Completed auth response example:
- 1.8 Cancel
- 1.9 Request:
- 1.10 Response:
  - 1.10.1 Cancelled response example:
- 1.11 QR
- 1.12 Request:
- 1.13 Response:
  - 1.13.1 Example:
- 1.14 Request:
- 1.15 Response:
- 1.16 Fault
  - 1.16.1 Example fault message:

General info

För att ansluta till tjänsten via API:et GRP eller måste Kunden ha ett så kallat ServiceID(policy), vilket fås av CGI. ServiceID:et kan ses som ett lösenord till tjänsten och det är unikt för varje kund.

Kundens ServiceID till produktion bör hållas konfidentiellt och hemligt. Kunden kan efter överenskommelse erhålla olika ServiceID om man från olika system vill använda sig av olika säkerhetsregler eller regler kring vilka certifikat som skall godkännas.

Several providers of electronic ID:s (Finansiell ID-Teknik, Freja eID, Secmaker) have similar API:s that customers can use to request authentication and signing operations. The GRP service wraps all these API:s into one, making the implementation of the different electronic ID:s much simpler for service providers. Consumers of the GRP API are called Relying Parties (RP:s).

Access info

You will need a header called accessToken with the API-key matching to the serviceId defined as a query parameter to access and make requests to any of the endpoints listed below.

Auth/Sign

POST request to https://eid-connect.test.funktionstjanster.se/grp/v3/init - Used for starting a authentication or a signing to a provider.

Request:

Query parameters:


serviceId	Yes	Relying parties identify themselves for the GRP API using the parameter "serviceId". This is a value assigned by the GRP service operator when signing up.	policy
provider	Yes	The relying party selects eID provider using the argument "provider". Examples are "bankid", "freja" and "nias"	provider
displayName	Yes	Name of the certificate to be used by the IdP	rpDisplayName
requestType	No	Which type of request, "AUTH" for authentication and "SIGN" for signing. Defaults to AUTH if not specified.
transactionId	Yes	A client provided random string unique for the specific authentication or sign request. UUID format is recommended. The same value is returned in the response and this is used for tracing and logging purposes.	transactionId
endUserInfo	Yes	IP-address of the end-user connected to the RP.	endUserInfo.IP_ADDR
orgIdIssuer	No	Only used for Freja Organisation ID. Can be set to "ANY" to allow organisation IDs set by other Relying Parties.
callInitiator	Conditional	Indicate if the user or RP initiated the phone call. Possible values are "USER" and "RP". NB: This must be present if flowType is set to "PHONE", as this is a required parameter for a BankID phone auth/sign request. Otherwise it can be left out or with an empty value.
flowType	No	Specify what type of flow the request is for. Currently only supports one value "PHONE", used for BankID phone auth/sign. Defaults to regular BankID auth/sign if not specified. NB: If this parameter is active and set to "PHONE", then it's required to also use the parameter "callInitiator".

Example

https://eid-connect.test.funktionstjanster.se/grp/v3/init?serviceId=cgitest001&provider=bankid&requestType=AUTH&displayName=CGI+Sverige+AB+Test&transactionId=l8ng1BYH&endUserInfo=127.0.0.1

Header:

Host: eid-connect.test.funktionstjanster.se

Accept-Encoding: gzip, deflate

Accept: */*

Content-Type: application/json

accessToken: 01010101-0101-0101-0101-010101010101

Body:

Body info

The request body is not optional (that is, you need to send in a empty body at minimum {}), but can optionally use these elements:


subjectIdentifier	User unique identifier, like SSN. For some eID provider it is always required, for others it is only required when eID is on another device
subjectIdentifier.type	Specifies subject identifier type. Currently used are: "TIN" (personnummer), "EMAIL" - user e-mail address.
userMessage
userMessage.nonVisible	Data to be signed, not displayed to user in the eID app. Should be Base64 encoded. Max length depends on the eID provider. Example for BankID is 200 000 characters after Base64 encoding.	userNonVisibleData
userMessage.visible	Text to be signed and displayed to user in the eID app. Should be a Base64 encoded UTF-8 string. Max length depends on the eID provider. Example for BankID is 40 000 characters after Base64 encoding.	userVisibleData
userMessage.format	Format of the visible text, types available are: PLAIN_TEXT, MARKDOWN, HTML

In the case of BankID, the userMessage.visible will be shown as "intention/avsikt" in an auth attempt.

Request body example:

{
  "subjectIdentifier": {
    "value": "19xxxxxxxx99",
    "type": "TIN"
  },
  "userMessage": {
    "nonVisible": "c2VjcmV0IHRleHQ=",
    "visible": "dGVzdCB0ZXh0",
    "format": "PLAIN_TEXT"
  }
}

Response:


refId	An order reference that should be used in subsequent calls to the collect endpoint.
autoStartToken	A unique token used by some providers to start the app on the same device.
qrStartToken	A token used to compute the animated QR code, not used by all providers
qrStartSecret	A token used to compute the animated QR code, not used by all providers
transactionId	The same transactionId that was provided in the request, used for tracing and logging purposes.

Successful auth attempt started response example:

{
    "refId": "2ba2p9xvg",
    "autoStartToken": "770f7e00-e00e-4d62-a7b7-24503849a6e8",
    "qrStartToken": "19633055-9c49-40a8-b567-75495f80dc0f",
    "qrStartSecret": "8cccc89c-04bd-46b9-baa6-5d23e822231c",
    "transactionId": "9a397519-0f9e-47b3-ab9e-e5b725d1883b"
}

Collect

GET request to https://eid-connect.test.funktionstjanster.se/grp/v3/collect
Used to get status and result from a authentication or signing.

Request:


refId	Yes	The value received in Authenticate / Sign response.	orderId
transactionId	Yes	A client provided random string unique for the specific authentication or sign request. UUID format is recommended. The same value is returned in the response and this is used for tracing and logging purposes.	transactionId

Response:


progressStatus	Object with status of the order
progressStatus.status	General status of the attempt. Possible values: COMPLETED, FAILED, CANCELLED, PENDING
progressStatus.substatus	Status from the provider
progressStatus.message	Status message from the provider
attributes	Key-value pairs with information from the certificate or sign/auth operation.
userInfo	Basic information about the user
userInfo.subjectIdentifier	Identifier of the subject
userInfo.subjectIdentifier.value	Unique identifier of the subject.
userInfo.subjectIdentifier.type	Specifies subject identifier type. Currently used are: "tin" (personnummer), "email" - user e-mail address.
userInfo.displayName	User display name. Used by some providers for given name + surname
userInfo.givenName	User given name
userInfo.sn	User surname
userInfo.tin	User TIN (personnummer)
userInfo.ipAddress	IP address of the eID client
validationInfo	Information about the validation. May contain the actual signature and OCSP response from certificate validation.
validationInfo.signature	Base64 encoded signature in the format specified by "signatureFormat".
validationInfo.signatureFormat	Current supported formats are: "xmldsig" - Standard XML based format used by BankID. "pkcs7" - PKCS#7, binary format used by NetID etc. "jws" - JSON Web Signature format used by Freja.
validationInfo.ocspResponse	Base64 encoded OCSP response (not available for all providers).
transactionId	The same transactionId that was provided in the request, used for tracing and logging purposes.

In progress auth attempt response example:

{
    "progressStatus": {
        "status": "PENDING",
        "substatus": "STARTED",
        "message": "IN_FREJA_START_THE_APP"
    },
    "attributes": null,
    "userInfo": null,
    "validationInfo": null,
    "transactionId": "9a397519-0f9e-47b3-ab9e-e5b725d1883b"
}

Completed auth response example:

Cancel

GET request to https://eid-connect.test.funktionstjanster.se/grp/v3/cancel
Used to cancel a authentication or signing

Request:


refId	Yes	The value received in Authenticate / Sign response.	orderId
transactionId	Yes	A client provided random string unique for the specific authentication or sign request. UUID format is recommended. The same value is returned in the response and this is used for tracing and logging purposes.	transactionId

Response:


progressStatus	Object with status of the order
progressStatus.status	General status of the attempt, should be CANCELLED
transactionId	The same transactionId that was provided in the request, used for tracing and logging purposes.

Cancelled response example:

QR

Endpoints that help with QR-code generation.

Request:

GET request to https://eid-connect.test.funktionstjanster.se/grp/v3/qr


refId	Yes	The value received in Authenticate / Sign response.
transactionId	Yes	A client provided random string unique for the specific authentication or sign request. UUID format is recommended. The same value is returned in the response and this is used for tracing and logging purposes.

Response:

The qr-endpoint returns a string-value that is to be qr-coded.

Example:

bankid.775ba483-fbf0-4a7a-8c25-83bd798abbd7.3.e9a6d4bd0b02c6bd9671e42c6a823cabe6c8bc12996e1906618646cc0677646c

Request:

GET request to https://eid-connect.test.funktionstjanster.se/grp/v3/qrImage


refId	Yes	The value received in Authenticate / Sign response.
transactionId	Yes	A client provided random string unique for the specific authentication or sign request. UUID format is recommended. The same value is returned in the response and this is used for tracing and logging purposes.
size	No	The size of the generated QR-code image (in pixels). Default is 200.

Response:

The qrImage-endpoint returns a qr-code image of the string returned by the qr-endpoint in .png format.

Fault

There are several error codes that can help if you are having problems:


ACCESS_DENIED_RP	The request was not allowed for the given provider. Check provider and accessToken.
INVALID_PARAMETERS	Could not handle request. Check input parameters.
RETRY	An error occurred. RP should not automatically retry, but let user try again.
INTERNAL_ERROR	Internal error in GRP or eID provider system.
EXPIRED_TRANSACTION	The operation has timed out and user needs to retry.
USER_CANCEL	The operation was cancelled by the user.
CLIENT_ERR	An error has occurred in the client.
CERTIFICATE_ERR	An error with the certificate has occurred.
CANCELLED	The operation was cancelled because another order for the same user was added.
START_FAILED	The client could not be started.
ALREADY_IN_PROGRESS	Another operation for the same user is already in progress. That order is cancelled and no new order is created. RP needs to try again.
SIGN_VALIDATION_FAILED	Validation of a signature could not be validated. Also applies to the signature of an authentication operation.
UNKNOWN_USER	Invalid user identifier. Used for some eID providers instead of INVALID_PARAMETERS.
MISSING_CALL_INITIATOR	No call initiator specified when the phone flow type is used.

API

General info

Auth/Sign

Request:

Query parameters:

Body:

Request body example:

Response:

Successful auth attempt started response example:

Collect

Request:

Response:

In progress auth attempt response example:

Completed auth response example:

Cancel

Request:

Response:

Cancelled response example:

QR

Request:

Response:

Example:

Request:

Response:

Fault

Example fault message: