1. Introduction

This document contains generated documentation for AMPnet identity service.

2. Authorization API

2.1. Get payload

Used to retrieve a unique nonce associated with user address.

Request
POST /authorize HTTP/1.1
Content-Type: application/json
Content-Length: 62
Host: localhost:8080

{
  "address" : "0xef678007d18427e6022059dbc264f27507cd1ffc"
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 95

{
  "payload" : "Welcome!\nClick “Sign” to sign in. No password needed!\nNonce: 28429021"
}

2.2. Get JWT

To get JWT the user must sign the payload received from POST /authorize route using his private key. User is created in the database on his first login.

Request
POST /authorize/jwt HTTP/1.1
Content-Type: application/json
Content-Length: 219
Host: localhost:8080

{
  "address" : "0xef678007d18427e6022059dbc264f27507cd1ffc",
  "signed_payload" : "0x631026f14811702b25ab826c405d3ed4951c15fd6bafe551adbfc79eb55fa7eb0221e739095661cb3cce7b754b9fb4fc9764eede725e0701beba3a1000fbcfbf1c"
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 751

{
  "access_token" : "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJBTVBuZXQiLCJhZGRyZXNzIjoiMHhlZjY3ODAwN2QxODQyN2U2MDIyMDU5ZGJjMjY0ZjI3NTA3Y2QxZmZjIiwiaWF0IjoxNjMzNTI0NDMxLCJleHAiOjE2MzM2MTA4MzF9.euI4-hvXb-piMuTBs614SowJm6wq7nJzBxdwxy5QT2QJTfn3GkrYCQuYGD2wZcjriFSOrdnY0eLR5JPYVpQFWmiT9Wc2MPhlDp8cgFyJcy88BFDoxpW1en84zJkvHr2ypNCqFrn6jMoANX0FiU4750wsy4b1XCDmIHIZIGsh3niKDeUEBdtDY-mHQCfMp1nUOl17IbU18xa1gzyPQ8W1w2ZjSQvK0VVy-LIpKH7GCGV_PFHVCxI-TgVFO5UQZ7-j4pWdWmXOVXwsL4JBV1xyzy3rkkxw8-QFUkw2pVhTH7ihc9Rjl_QgHRQkzdvd5NQ7gxZasNJTU4JJzoSBxT7Ekw",
  "expires_in" : 86400000,
  "refresh_token" : "2pBH0rFqtwOaHDC8Jyz4YGSFqpHRvO1pSl8UbStDe2MvYDoNBHam4TdcMfDizus70lbHoLiDimBkn9pF5076xsYN5t-dpkFq5quDX9n5q6JfIvozK2doV6EKn0gd6fFq",
  "refresh_token_expires_in" : 7776000000
}

2.3. Refresh token

Request
POST /authorize/refresh HTTP/1.1
Content-Type: application/json
Content-Length: 59
Host: localhost:8080

{
  "refresh_token" : "9asdf90asf90asf9asfis90fkas90fkas"
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 656

{
  "access_token" : "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJBTVBuZXQiLCJhZGRyZXNzIjoiMHhlZjY3ODAwN2QxODQyN2U2MDIyMDU5ZGJjMjY0ZjI3NTA3Y2QxZmZjIiwiaWF0IjoxNjMzNTI0NDMxLCJleHAiOjE2MzM2MTA4MzF9.euI4-hvXb-piMuTBs614SowJm6wq7nJzBxdwxy5QT2QJTfn3GkrYCQuYGD2wZcjriFSOrdnY0eLR5JPYVpQFWmiT9Wc2MPhlDp8cgFyJcy88BFDoxpW1en84zJkvHr2ypNCqFrn6jMoANX0FiU4750wsy4b1XCDmIHIZIGsh3niKDeUEBdtDY-mHQCfMp1nUOl17IbU18xa1gzyPQ8W1w2ZjSQvK0VVy-LIpKH7GCGV_PFHVCxI-TgVFO5UQZ7-j4pWdWmXOVXwsL4JBV1xyzy3rkkxw8-QFUkw2pVhTH7ihc9Rjl_QgHRQkzdvd5NQ7gxZasNJTU4JJzoSBxT7Ekw",
  "expires_in" : 86400000,
  "refresh_token" : "9asdf90asf90asf9asfis90fkas90fkas",
  "refresh_token_expires_in" : 7772400000
}

3. KYC API

For KYC procedure the system supports Veriff provider.

3.1. Get Veriff session

Get Veriff session. For code explanation on decision response, see: https://developers.veriff.com/#response-and-error-codes Request requires header: Authorization: Bearer JWT.

Request
POST /veriff/session HTTP/1.1
Content-Type: application/json
Host: localhost:8080
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 423

{
  "verification_url" : "https://alchemy.veriff.com/v/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.new-url",
  "state" : "created",
  "decision" : {
    "session_id" : "44927492-8799-406e-8076-933bc9164ebc",
    "status" : "declined",
    "code" : 9102,
    "reason" : "Physical document not used",
    "reason_code" : 101,
    "decision_time" : "2020-12-04T10:45:37.907Z",
    "acceptance_time" : "2020-12-04T10:45:31.000Z"
  }
}

3.2. Handle Veriff session

Request
POST /veriff/webhook/decision HTTP/1.1
Content-Type: application/json
X-AUTH-CLIENT: a2b3005f-e324-4e7e-a328-4aecd11a091b
X-SIGNATURE: fa3449ca55ea7a0fbb50e9a6c19bcae2079b0dee3332abeb172213096b521802
Content-Length: 1260
Host: localhost:8080

{
  "status" : "success",
  "verification" : {
    "id" : "12df6045-3846-3e45-946a-14fa6136d78b",
    "code" : 9001,
    "person" : {
      "gender" : null,
      "idNumber" : null,
      "lastName" : "MORGAN",
      "firstName" : "SARAH",
      "citizenship" : null,
      "dateOfBirth" : "1967-03-30",
      "nationality" : null,
      "yearOfBirth" : "1967",
      "placeOfBirth" : "MADRID",
      "pepSanctionMatch" : null
    },
    "reason" : null,
    "status" : "approved",
    "comments" : [ ],
    "document" : {
      "type" : "DRIVERS_LICENSE",
      "number" : "MORGA753116SM9IJ",
      "country" : "GB",
      "validFrom" : null,
      "validUntil" : "2022-04-20"
    },
    "reasonCode" : null,
    "vendorData" : "0xef678007d18427e6022059dbc264f27507cd1ffc",
    "decisionTime" : "2019-11-06T07:18:36.916Z",
    "acceptanceTime" : "2019-11-06T07:15:27.000Z",
    "additionalVerifiedData" : {
      "driversLicenseCategory" : {
        "B" : true
      }
    },
    "riskLabels" : [ {
      "label" : "document_crosslinked_with_fraud",
      "category" : "document"
    }, {
      "label" : "document_globally_crosslinked_with_multiple_declines",
      "category" : "document"
    } ]
  },
  "technicalData" : {
    "ip" : "186.153.67.122"
  }
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

3.3. Handle Veriff event

Request
POST /veriff/webhook/event HTTP/1.1
Content-Type: application/json
X-AUTH-CLIENT: a2b3005f-e324-4e7e-a328-4aecd11a091b
X-SIGNATURE: bf3da6e9aa47e6be208fec283097a5bcbdb2066dcb58f0d7c9879637700f013f
Content-Length: 231
Host: localhost:8080

{
  "id" : "cbb238c6-51a0-482b-bd1a-42a2e0b0ff1c",
  "code" : 7001,
  "action" : "submitted",
  "feature" : "selfid",
  "attemptId" : "fa3316d6-0222-407e-927d-e75545a11ce6",
  "vendorData" : "2652972e-2dfd-428a-93b9-3b283a0a754c"
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

4. User API

All requests need header: Authorization: Bearer JWT.

4.1. Get user data

Request
GET /user HTTP/1.1
Content-Type: application/json
Host: localhost:8080
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 145

{
  "address" : "0xef678007d18427e6022059dbc264f27507cd1ffc",
  "email" : "[email protected]",
  "email_verified" : true,
  "kyc_completed" : true
}

4.2. Update user email

Request
PUT /user HTTP/1.1
Content-Type: application/json
Content-Length: 37
Host: localhost:8080

{
  "email" : "[email protected]"
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 151

{
  "address" : "0xef678007d18427e6022059dbc264f27507cd1ffc",
  "email" : "[email protected]",
  "email_verified" : true,
  "kyc_completed" : false
}

4.3. Whitelist address for issuer

User must complete KYC to enable whitelisting his address for any issuer.

Request
POST /user/whitelist HTTP/1.1
Content-Type: application/json
Content-Length: 91
Host: localhost:8080

{
  "issuer_address" : "0xb070a65b1dd7f49c90a59000bd8cca3259064d81",
  "chain_id" : 80001
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

4.4. Logout

Request
POST /user/logout HTTP/1.1
Host: localhost:8080
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

4.5. Pinata JWT

Generate Pinata JWT for pinning(storing) files to Pinata IPFS. JWT is generated for a limited number of usages. It is recommended to generate a new one before storing data to Pinata IPFS.

Request
GET /user/pinata HTTP/1.1
Content-Type: application/json
Host: localhost:8080
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 89

{
  "pinata_api_key" : "api-key",
  "pinata_api_secret" : "api-secret",
  "JWT" : "JWT"
}

5. Test API

5.1. Verify User with Test Data

Request needs header: Authorization: Bearer JWT.

5.2. Verify user

Request
POST /test/kyc HTTP/1.1
Content-Type: application/json
Content-Length: 110
Host: localhost:8080

{
  "address" : "0xef678007d18427e6022059dbc264f27507cd1ffc",
  "first_name" : "John",
  "last_name" : "Doe"
}
Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 145

{
  "address" : "0xef678007d18427e6022059dbc264f27507cd1ffc",
  "email" : "[email protected]",
  "email_verified" : true,
  "kyc_completed" : true
}