Introduction

Auth eID is an electronic identification (eID) solution for end users and organisations which can be used for identification, authentication and signing. The essential part of Auth eID service is a mobile application used for login and signing to all services that are connected to the Auth eID

Auth eID allows end users to participate at two levels. The first is an entry-level registration flow where user will have to confirm an e-mail address to be allowed,for example, login authentication in situations where an absolute identity is not of significance for the Relying Party.

Relying parties can make different Auth eID API calls depending on their needs. Our Device Key API call protects keys required to perform specific functions. WithAuthentication Requests Auth eID authenticate users for login. Signing requests are used when a digital signature is required for a specific transaction.

However, other API calls require that the end user has successfully gone through the onboarding process. The onboarding process involves, amongst other controls, verifying phone number, scanning ID documents, taking a selfie and uploading a proof of residency. Onboarded users can be involved in interactions with Relying Parties that involve login, but which also requires identity verification. Identification request API calls are made when Relying Parties requires users full name, date of birth and address. KYC Request are suitable for Relying parties who need to conduct their own due diligence and require extensive user details such as passport details, selfie, proof of residency and a screening result from a sanction list control and Politically exposed person (PEP) check.

This document contains instructions for Relying parties on how to securely transmit the information to Auth eID. This is a technical document aimed at software architects and developers.

How to begin

1. Onboarding

Signing up and joining as a Relying Party is very easy. First, you will have to download Auth eID on your mobile device, create a personal account and verify yourself with Auth eID. This gives you an insight of what your clients will go through to use the service.

2. Let’s get started

Sign up as a Relying Party through our webpage. Tell us more about the Company by filling out the form. Pick a monthly plan that fits your business (Basic/Advanced/Pro). Remember that Basic is free of charge and perfect for new Relying Parties. You can always change your plan once you are signed up. Read and accept the relying party agreement before you sign your application with your Auth eID. Add your credit card details (Required for business plan Advanced and Pro)

3. Integrate with Auth eID

The integration is very smooth and done via an API. Your API keys are available once you sign up.

4. We support you

Except of managing digital identities for you, we are happy to help with your technical integration. Just let us know ([email protected]).

Request

Creating request

To initiate request Relaying Party (RP) sends request to the Auth eID server and receives request ID that would be needed to retrieve request result or cancelling request from the RP side.

Auth eID app could be opened automatically if request is made from native mobile OS app (Android and iOS are supported). Please see Android and iOS examples on how use in-app links.

HTTP Request

POST https://api.autheid.com/v1/requests

gRPC Request

rpc Create(CreateRequest) returns (CreateResponse);

$ curl --request POST https://api.staging.autheid.com/v1/requests \
    --Header "Content-Type: application/json" \
    --Header 'Authorization: Bearer Pj+GIg2/l7ZKmicZi37+1giqKJ1WH3Vt8vSSxCuvPkKD' \
    --data '{"email":"[email protected]","title":"Test","type":"KYC"}'

  Rp.CreateRequest request = Rp.CreateRequest.newBuilder()
          .setTitle("Test").setEmail("[email protected]").setType(Rp.RequestType.KYC).build();
      Rp.CreateResponse response = blockingStub.create(request);

  import grpc
  import rp_pb2
  import rp_pb2_grpc

  def send_request(stub):
    create_request = rp_pb2.CreateRequest()
    create_request.title = "Test"
    create_request.email = email
    create_request.type = rp_pb2.KYC
    create_request.kyc.files_format = rp_pb2.EMBEDDED
    create_response = stub.Create(create_request, metadata=metadata)

  channel channel = new Channel("api.staging.autheid.com", channelCredentials);
  var client = new Requests.RequestsClient(channel);
  var request = new CreateRequest();
  var reply = client.Create(request);

  let url2 = URL(string: baseUrl + "/requests")!
  var request = URLRequest(url: url2)
  request.setValue("Bearer " + apiKey, forHTTPHeaderField: "Authorization")
  request.setValue("application/json", forHTTPHeaderField: "Content-Type")
  request.httpMethod = "POST"
  request.httpBody = jsonData

  let task = URLSession.shared.dataTask(with: request) { data, response, error in
    guard let data = data, error == nil else {
        print(error?.localizedDescription ?? "No data")
        return
    }
    let responseJSON = try? JSONSerialization.jsonObject(with: data, options: [])
  }

Body Parameters

Name	Type	Description	Notes
`type`	Enum	Request type: `AUTHENTICATION`, `SIGNATURE`, `IDENTIFICATION` or `KYC`, more details below	Required
`email`	Optional	User identification. Users might add and remove emails so this might change for the same user. Use `unique_user_id` from the request response to reliable detect same accounts. Either `email` or `use_local_account` must be set.	Optional
`use_local_account`	Boolean	For intra-mobile calls (using native mobile application or mobile browser) `email` could be empty if this field is set. See below.	Optional
`timeout_seconds`	Integer	Duration of time in seconds while user could sign request. Valid range is [10..600]. Default is 60	Optional
`title`	String	Request title. Will be visible in the app when user is prompted to sign request. Maximum is 100 symbols and one line	Required
`description`	String	Request description. Will be visible in the app when user is prompted to sign request. Maximum is 1024 symbols and up to ten lines	Optional
`authenticate`	Object	Optional data for authentication request. More details below	Optional
`signature`	Object	Optional data for signature request. More details below	Optional
`kyc`	Object	Optional data for KYC request. More details below	Optional

Response

{
  "success": true,
  "request_id": "JHgBYyLjUsJkKktsclwkMfkcv8MRgLkrubwzHBdnIJ4c",
  "timestamp_created": 1552650262
}

Name	Type	Description
`success`	Boolean	Boolean value to make sure request was successfully created
`request_id`	String	Unique request identificator
`timestamp_created`	Integer	Timestamp in seconds since Unix epoch (1 January 1970 UTC)

Retrieving request result

Request result will be available using this API call:

HTTP Request

GET https://api.autheid.com/v1/requests/{requestId}

gRPC Request

rpc GetResult(GetResultRequest) returns (GetResultResponse);

This methods is blocking and result would be sent when request status is determined (so it might block for up to timeout_seconds period). If non-blocking method is preferred please poll request status first (see below).

Request results are available for 5 minutes after signing. After that "not found" error returned instead.

Response

Name	Type	Description
`success`	Boolean	Indicates that request result was retreived succefully (this is different from the request status itself)
`status`	Enum	Request status (see below)
`status_code`	Integer	Request status code (see below)
`request_id`	String	Unique request identificator
`device_id`	String	Unique installation ID of the Auth eID app used to sign request if request was signed succesfully
`device_name`	String	Model of the mobile device used to sign request if request was signed succesfully
`email`	String	Email address used creating request
`unique_user_id`	String	Unique key to identify account that is persistent between accounts restores and emails adding/removing
`timestamp_created`	Integer	Timestamp when request was created
`timestamp_finished`	Integer	Timestamp when request has been finished
`authentication`	Object	Authentication details if request succeed. See below.
`signature`	Object	Signature details if request succeed. See below.
`identification`	Object	Identification details if request succeed. See below.
`kyc`	Object	KYC details if request succeed. See below.
`device_key`	Object	Device Key details if request succeed. See below.

Statuses

Name	Code	Description
`SUCCESS`	10000	Successful request result. User have signed request
`NOT_READY`	20001	Request is not ready yet. This status is used only with request status polling API
`TIMEOUT`	20002	Request is timed out before user signed it. This might also happen when account is not known to Auth eID
`RP_CANCELLED`	20003	Request was cancelled by RP using cancel API call
`USER_CANCELLED`	20004	User have cancelled request from mobile app
`ACCOUNT_NOT_VERIFIED`	20005	User have signed request but his account is not verified yet or passport expired. RP might limit `SIGNATURE` and `AUTHENTICATION` requests to verified accounts only. For `IDENTIFICATION` and `KYC` requests user must have verified account

Retrieving request status

Request status are available for 5 minutes after signing. After that "not found" error returned instead.

HTTP Request

GET https://api.autheid.com/v1/requests/{requestId}/status

gRPC Request

rpc GetStatus(GetStatusRequest) returns (GetStatusResponse);

Response

Name	Type	Description
`success`	Boolean	Indicates that the requesting status succeed (this is different from the request status itself)
`status`	Enum	Request status. See above
`status_code`	Integer	Request status as number

Cancelling request

HTTP Request

POST https://api.autheid.com/v1/requests/{requestId}/cancel

gRPC Request

rpc Cancel(CancelRequest) returns (CancelResponse);

Intra-mobile calls

When request is made in the same device (from native mobile application or from mobile browser) user might skip entering his id (email address). In this case RP should make request with use_local_account flag set. Auth eID server will return new request ID but won't send it anywhere. After that RP should try to open this URL on mobile device:

From mobile browser:

https://autheid.com/app/requests/?request_id=<REQUEST_ID>&callback=<OPTIONAL_CALLBACK_URL>&email=<OPTIONAL_EMAIL>

From native application:

autheid://autheid.com/app/requests/?request_id=<REQUEST_ID>&callback=<OPTIONAL_CALLBACK_URL>&email=<OPTIONAL_EMAIL>

String url = "autheid://autheid.com/app/requests/?request_id=" + requestId;
Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(url));
try {
  startActivity(intent);
} catch (ActivityNotFoundException e) {
  showMessage("Auth eID is not installed");
}

let url = "autheid://autheid.com/app/requests/?callback=autheiddemo%3A%2F%2Ftest&request_id=" + self.requestId
UIApplication.shared.open(URL(string: url)!, options: [:]) {
  (success) in
    if (!success) {
      self.showMessage("Auth eID is not installed")
  }
}

Complete examples are avilable in the samples repository.

callback parameter is optional. If set, Auth eID mobile application will open it when request is done (whether it succeed or failed). It could be regular web page (will be opened in mobile browser) or URL with custom scheme for the RP's native application. If not set, on Android Auth eID app will close itself when request is done. On iOS RP should use callback for better user experience.

Parameters must be URL encoded as usual (not needed for request_id as it uses only URL-safe symbols).

If account has multiple associated email addresses this will open email selection dialog. If this is not desired and specific email address is already known, RP could pass it in email parameter. This will automatically select account's email if it available (or will show error message otherwise). Please note that RP should not pass email parameter when request is registered on the server for local requests even if it is known.

Errors

If any REST API call failed for some reasons this error message returned instead:

Name	Type	Description
`error`	Enum	Error code (subset of gRPC status codes). See below
`error_code`	Integer	Error code as number
`message`	String	Textual description of the error

Error codes:

Name	Code	Description
`INVALID_ARGUMENT`	3	Invalid input parameters. Request must not be resend before fixing the problem
`NOT_FOUND`	5	Requested item was not found (unknown request ID, file not found etc)
`PERMISSION_DENIED`	7	RP is known but has no access to this resource
`FAILED_PRECONDITION`	9	There might be a problem with RP account
`UNAUTHENTICATED`	16	RP is not known

For gRPC API equivalent status codes used instead.

Authorization

All end-points require RP authorization. Auth eID server uses bearer tokens for RP authorization. RP must set own API key in the Authorization header (HTTP request's header for the REST API or request's metadata for the gRPC API). API keys will be available in the RP client's portal after registration. With test environment test API key should be used instead.

Request types

Authentication

Body Parameters

{
  "success": true,
  "status": "SUCCESS",
  "status_code": 10000,
  "request_id": "lgayNDC_tyUPgf9GuTfjNl6kbwCrUk6e5sZUaU4Sqksu",
  "device_id": "Awiuhl1V7yqmZUDM5SMlO1YQwbV+VN8bBKzQ/5oDZtQh",
  "device_name": "iPhone 7",
  "email": "[email protected]",
  "unique_user_id": "oava51cj",
  "authentication": {
    "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1NTI3NDkwMzgsImlzcyI6ImF1dGhlaWQuY29tIiwic3ViIjoidGVzdEBleGFtcGxlLmNvbSJ9.CMc1DZe9IxVf1vjbrhSM14hnGL_oL-HzNPxYzp-MsscP5BK2mK4ZbFGDBYXHi6e2h0J1I6Lkutl5NnjyvCR6TMZ7G-heFMwCZ4J0XDpwnVc4PRtbOQWQ1bJT_CIqmWjTEjwCIrh3IQIJ7uLgs4b_sNre5x2AGTr-rH9HF5rdJw_ArsoeGEAlUGprJeTGV_IrZFsKKj4MUpOTtZU8I9UJu-lNcobo1IQ0B0cPgrJv7DdEdiZ5h1kMPfU0eP9hxsLxGtS-Urbcm49yQwB1xOomzYRKFGuZ9lKYFEfyfIYps0fRVsVKmhm6KmJG4irv0eWfNqtDT6Hn1fQ0iJSWKBhqUA",
    "is_verified": true
  }
}

Name	Type	Description	Notes
`verified_only`	Boolean	If set, only verified users will be able authenticate himself. Default is false	Optional

Response

Name	Type	Description	Notes
`jwt`	String	JWT token for the user's account signed by Auth eID	Required
`is_verified`	Boolean	Shows if account is verified or not	Required

Signature

User signs requests on mobile app using secured private key. Auth eID verifies that the signature is valid and that account is active.

Body Parameters

{
  "success": true,
  "status": "SUCCESS",
  "status_code": 10000,
  "request_id": "bZGRPCgF0D71x-49DkjzOzyXdRTGyZ0w_OSkqWcT5fTq",
  "device_id": "Awiuhl1V7yqmZUDM5SMlO1YQwbV+VN8bBKzQ/5oDZtQh",
  "device_name": "iPhone 7",
  "email": "[email protected]",
  "unique_user_id": "oava51cj",
  "signature": {
    "signature_data": "eyJlbWFpbCI6InRlc3RAZXhhbXBsZS5jb20iLCJycE5hbWUiOiJBdXRoIGVJRCBUZXN0IiwidGl0bGUiOiJUZXN0IiwiZGVzY3JpcHRpb24iOiIiLCJ0aW1lc3RhbXAiOjE1NTI3NDkyNDAsInRpbWVvdXRTZWNvbmRzIjowLCJyYVB1YktleSI6IiIsImludmlzaWJsZURhdGEiOiIifQ==",
    "sign": "d0eIau0SCEEDtodxfo7V0apOfSXUw1t9PSZWfExd06+473JWp/ltC19l5r2V7BwBzZSlhgi/DSx75ZbB1jir8A==",
    "is_verified": true
  }
}

Name	Type	Description	Notes
`serialization`	Enum	Signed data format. Available formats are `SERIALIZATION_JSON` and `SERIALIZATION_PROTOBUF`. Default is `SERIALIZATION_JSON`	Optional
`invisible_data`	Binary	Invisible data that will be copied as-is in the signature response	Optional
`verified_only`	Boolean	If set, only verified users will be able sign request. Default is false	Optional

Response

Name	Type	Description	Notes
`serialization`	Enum	Signed data format. See above.	Required
`signature_data`	Binary	Binary data signed by the user	Required
`sign`	Binary	Digital signature by user's private key	Required
`is_verified`	Boolean	Shows if account is verified or not	Required

Identification

Response

{
  "success": true,
  "status": "SUCCESS",
  "status_code": 10000,
  "request_id": "eMizOqNCEI0kC5vpgJnbJKrXb8SQ880ncoL1KHTahVcT",
  "device_id": "A05mecU3ob6HWhbXu4EDuC23pjV0ChoZtXwLDJhouGJG",
  "device_name": "iPhone 7",
  "email": "[email protected]",
  "unique_user_id": "hoxzi7ey",
  "timestamp_created": 1556956040,
  "timestamp_finished": 1556956041,
  "identification": {
    "first_name": "TEST",
    "last_name": "SPECIMEN",
    "phone_number": "+46 1234567890",
    "gender": "M",
    "date_of_birth": "1980-01-01",
    "nationality": "SWE",
    "personal_number": "98765432",
    "residency_country": "SWE",
    "residency_city": "Malmo",
    "residency_postcode": "211 25",
    "residency_address": "Ostergatan 21"
  }
}

Name	Type	Description	Notes
`first_name`	String	User's first name	Required
`last_name`	String	User's last name	Required
`phone_number`	String	Verified client's phone number	Required
`gender`	String	could be "M"/"F" or empty if not set in the passport	Optional
`date_of_birth`	String	Date of birth in ISO 8601 format (ie 2018-12-31)	Required
`nationality`	String	Country of the nationality (ISO 3166-1 alpha-3)	Required
`personal_number`	String	Personal number from the passport if available	Optional
`residency_country`	String	Residency country (ISO 3166-1 alpha-3 format)	Required
`residency_city`	String	Residency city in (ISO 3166-1 alpha-3 format)	Required
`residency_postcode`	String	Residency postcode	Required
`residency_address`	String	Residency address	Required
`residency_address2`	String	Residency address line 2	Optional

Know-Your-Customer (KYC)

Body Parameters

Name	Type	Description	Notes
`files_format`	Enum	How additional KYC documents will be available. `DOWNLOAD_LINK` - as download link (default), `EMBEDDED` - as binary field	Optional

Response

{
  "success": true,
  "status": "SUCCESS",
  "status_code": 10000,
  "request_id": "URI4TsaRVCvzJH1oUBotbKNUiRQarZs7JMRWw33GT-Af",
  "device_id": "Awiuhl1V7yqmZUDM5SMlO1YQwbV+VN8bBKzQ/5oDZtQh",
  "device_name": "iPhone 7",
  "email": "[email protected]",
  "unique_user_id": "oava51cj",
  "kyc": {
    "identification": {
      "first_name": "TEST",
      "last_name": "SPECIMEN",
      "gender": "M",
      "date_of_birth": "1980-01-01",
      "nationality": "SWE",
      "personal_number": "98765432",
      "residency_country": "SWE",
      "residency_city": "Malmo",
      "residency_postcode": "211 25",
      "residency_address": "Ostergatan 21"
    },
    "passport_issuing_state": "SWE",
    "passport_number": "111222333",
    "passport_expiration": "2020-01-01",
    "screening_EU": "NO_MATCH_FOUND",
    "screening_UN": "NO_MATCH_FOUND",
    "screening_PEP": "NO_MATCH_FOUND",
    "phone_number": "+46 1234567890",
    "kyc_pdf": {
      "download_link": "https://api.staging.autheid.com/v1/requests/URI4TsaRVCvzJH1oUBotbKNUiRQarZs7JMRWw33GT-Af/files/kyc.pdf"
    },
    "residency_proof_pdf": {
      "download_link": "https://api.staging.autheid.com/v1/requests/URI4TsaRVCvzJH1oUBotbKNUiRQarZs7JMRWw33GT-Af/files/residency.pdf"
    }
  }
}

Name	Type	Description	Notes
`identification`	Object	Identification information same as in identification response. See above	Required
`passport_issuing_state`	String	Country that issues passport (in ISO 3166-1 alpha-3 format)	Required
`passport_number`	String	Passport's number	Required
`passport_expiration`	String	Passport's expiration date in ISO 8601 format (ie 2018-12-31)	Required
`screening_EU`	Enum	Screening result for the EU sanction's list. Possible values `MATCH_FOUND` and `NO_MATCH_FOUND`	Required
`screening_UN`	Enum	Same as above but for the UN sanction's list	Required
`screening_PEP`	Enum	Same as above but for the politically exposed persons (PEP) list	Required
`screening_EU_info`	String	Human readable screening result information if match found in the EU sanction's list	Optional
`screening_UN_info`	String	Same as above but for UN sanction's list	Optional
`screening_PEP_info`	String	Same as above but for PEP list	Optional
`phone_number`	String	Verified client's phone number	Required
`kyc_pdf`	Object	KYC PDF document. See below	Required
`residency_proof_pdf`	Object	Same as above but with residency proof details	Required

Files information:

Name	Type	Description	Notes
`download_link`	String	Link where PDF document could be downloaded. Please note that this request also requires RP authorization	Optional
`embedded`	Binary	Embedded PDF document itself	Optional

There will be only one field set depending on KYC request type. By default PDF files will be available as URLs.

Device Key

Device keys are secure keys generated in the mobile app. They could be used to protect secrets (bitcoin wallets, encrypted archives etc). Device keys are generated inside the app (and used seed never leaves device). Seed is protected by PIN code (enforced by Auth eID server). Device key is optionally encrypted so only RP agent could decrypt it. Key is derived from key_id (supplied by RP agent), unique RP seed (generated and stored on Auth eID server) and device seed (generated and stored in the app). Please note that old device keys would be lost if device is removed and added later or account is restored.

Device keys could be optionally encrypted in the mobile app (so Auth eID server could not know it). Please see C++ example if encryption required.

Body Parameters

Name	Type	Description	Notes
`key_id`	String	Key ID that is used to generate unique key	Required
`use_new_devices`	Boolean	If set then requests would be sent to only unknown devices (from the `known_device_ids` list. Otherwise requests would be sent to only known devices)	Optional
`known_device_ids`	String List	Already known to RP device IDs Optional	Optional
`register_key`	Enum	Register or not new `key_id` in the app settings info. `KEEP` - do not update list (default), `REPLACE` - clear list and register as new, `ADD` - add registration to the list, `CLEAR` - clear list	Optional

Response

{
  "success": true,
  "status": "SUCCESS",
  "status_code": 10000,
  "request_id": "c7NCKZhfkzR8y1ghpNeaXAD-hegjkS0poHRA5GlKbU4R",
  "device_id": "A9eIMRIb+qRG8+NEPv3m8c6AjTv07cNs+y2/TquZR54K",
  "device_name": "iPhone 7",
  "email": "[email protected]",
  "unique_user_id": "q914fg5f",
  "device_key": {
    "request_id": "c7NCKZhfkzR8y1ghpNeaXAD-hegjkS0poHRA5GlKbU4R",
    "timestamp": 1553954189,
    "device_key": "b/GIibBPyxUw4Mo7+R51Mjc0cfdGBPumb8NZ+e3GmXU="
  }
}

Name	Type	Description	Notes
`request_id`	String	Request ID	Required
`timestamp`	Integer	Timestamp	Required
`device_key`	Binary	Generated key	Required

Production environment

Server: api.autheid.com

API keys: https://autheid.com/api-keys

Test environment

Server: api.autheid.com

Please use test API keys from the client portal: https://autheid.com/api-keys

Requests to the test environment are not accounted in the billing.

To connect from mobile app to the test environment please toggle license acceptance switch 6 times. On main app screen there should be text saying Staging server after account activation).

Test accounts with auto sign (after 10 seconds):

Email	Type
[email protected]	Verified account
[email protected]	Unverified account
[email protected]	Verified account with EU sanctions list match
[email protected]	Verified account with PEP list match

API

There are REST API and gRPC end-point API available. Please see demo applications for more information. Main protocol specification is gRPC schema (rp.proto file).

Auth eID gRPC API specification

OpenAPI / Swagger UI (schema generated from rp.proto with gRCP gateway)

Examples

Examples for Java, .NET, C++, Python (gRPC) and Android / iOS (REST) clients.