Skip to content

Authorization

Jump to bottom
ndzlatar edited this page Dec 30, 2021 · 8 revisions

The digi.me authorization flow enables websites or applications (consumers) to access protected resources via the digi.me Public API (service provider), without requiring users to disclose their digi.me credentials to the consumers.

Authorization Request

Request Header

Parameter Required Description Type
Authorization Yes Authentication type. Use Bearer and a JWT token. The JWT should be a string in the format xxxxx.yyyyy.zzzzz. Learn more about JWT creation. string
Accept Yes The content types, expressed as MIME types, the client is able to understand. Use application/json. string

The JWT payload for the Authorization string:

{
  "access_token": <access_token>,
  "client_id": <appId_contractId>,
  "code_challenge": <Base64UrlEncoded(SHA256(code_verifier))>,
  "code_challenge_method": "S256",
  "nonce": <^[a-zA-Z0-9]{32}$>,
  "redirect_uri": <registered_redirect_uri>,
  "response_mode": "query",
  "response_type": "code",
  "state": <random_string>,
  "timestamp": <current_unix_time>
}
Property Required Description Data type
access_token No Previously received access_token can be used to restore user context. string
client_id Yes A string consisting of the application ID and contract ID separated by an underscore. ie appId_contractId. string
code_challenge Yes Base64-URL-encoded string of the SHA256 hash of the code_verifier. See PKCE for details. string
code_challenge_method Yes Method used to verify code challenge. Use the value S256. string
nonce Yes A 32-char string made up of random alphanumeric characters. string
redirect_uri Yes The URI to return the user to after authorization is complete, defined in the contract. string
response_mode Yes Indicates how the result of the authorization request is returned. Use the value query. string
response_type Yes Indicates the grant type to be carried out. Use the value code. string
state No Any extra information you'd like to attach. string
timestamp Yes Unix timestamp in seconds. number

Proof Key for Code Exchange (PKCE)

Learn more about the code_challenge and code_challenge_method with PKCE.

Request Body

Parameter Required Description Type
limits No Session limits to specify different limitations, ie for how long to wait for new data, for more details check session [Limit]
scope No Session Scope to specify which subset of data the contract scope will be returned, for more details check session [Scope]

Sample Request

curl -i -X POST \
   -H "Accept:application/json" \
   -H "Authorization:Bearer eyJhbGciOiJQUzUxMiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJJTDdhUFlXTzZEVWFVOWtnWTdad0hwVjFHN0FlQkhRVF9xWWZqR2kwRmdaY01wa1pqekZRMW56NXU3VFg5bEZjWSIsImNvZGVfY2hhbGxlbmdlIjoiUjFyaVJhYnhaazRzeFZBR3Y0cjQtaGFyUGxldGYtWjdOZjdRQWhzTElSWSIsImNvZGVfY2hhbGxlbmdlX21ldGhvZCI6IlMyNTYiLCJub25jZSI6ImpjVjd2VTh1VktrUm1wbXFVMm1GMnBGNDRxUFBmQ3oxIiwicmVkaXJlY3RfdXJpIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgxL2N5Y2xpYy1yZXN1bHRzIiwicmVzcG9uc2VfbW9kZSI6InF1ZXJ5IiwicmVzcG9uc2VfdHlwZSI6ImNvZGUiLCJzdGF0ZSI6InVzZXJJZD1HTkV2LXVqSjMmYXBwSWQ9SUw3YVBZV082RFVhVTlrZ1k3WndIcFYxRzdBZUJIUVQmY29udHJhY3RJZD1xWWZqR2kwRmdaY01wa1pqekZRMW56NXU3VFg5bEZjWSIsInRpbWVzdGFtcCI6MTYwNDY2OTM0MzY1N30.BvgojK5zCzV_veNKsFElPqmn3Cv_OS_pvkSwBdohKeYN8m5aotbsi_b3O_pE2dqpzraXVMRve7UiWUZYr7StGdqbVtMSranBQrBeRB7sw5yikyTbK0Jeg9BkEzpkzNELm88ysjOoU31GnoPFh4g9Q-ka5kITdNRII13ZwPRuVyAC7nSC64yEOA3oojqd_D6hTCRk8LQg4zY-nAoq3kyXiGlE3gRDSk9eKFDIwpINrctRRNr0sDuTZf811fPwbbtS9wznDUKTW-iZMuF7aXz9RyO2scYZkIpGknu6vP4IZmrQOpj-3hF-mtXYkTrivkkeUbBD0Sd_m_gFc0oTns4VIQ" \
 'https://api.digi.me/v1.6/oauth/authorize'

Sample Response

201 Created
{
  "session": {
    "expiry": number,
    "key": string,
  },
  "token": "eyJhbGciOiJQUzUxMiIsImprdSI6Imh0dHBzOi8vYXBpLmludGVncmF0aW9uLmRldmRpZ2kubWUvdjEvandrcy9vYXV0aCIsImtpZCI6Imh0dHBzOi8vZGlnaW1lLWFscGhhLWtleS12YXVsdC52YXVsdC5henVyZS5uZXQva2V5cy9vYXV0aC81ZTVmOGQwNGE4ZTU0Y2RlODUwNjIzMGZjZTBhOGJlOSIsInR5cCI6IkpXVCJ9.eyJwcmVhdXRob3JpemF0aW9uX2NvZGUiOiI5MmJiNTczMzZhYWZhMmYyMWMzYzJlODk1YWMzMDQ3NTE3NWMzNDljMzVkMTNjMWQ2ZDhlNTIwOGRiMDg0YjNmMmE3N2UwOTBkNTYyMjIyYjUzMjc1OGU5YjE1YmFmY2NmYjJjNjQ1MTNiMjQ4NDFiZGZlNjk4YTRlM2I1OTIzMTNmYzcyOTY4OWI4NDViZGYyYTEwNzJhOTJhMGM2NmQyIn0.WBezjgo2TBoBS37478raNKpfAtccXObVeCoKhMvFNKkd2asRN2bH6-V03GPzMBM8lTFZlHyofLPjnrFBqVNyG5YoP98DeR84lhqSN7h4Bpd8tv6EYRy6_yHo6PcswuONpm0QGQ5Pgt9eCKpUGHC_bBrVUo2BlSJSGD35RcdccfcMcVBQj5MOARjWL_fBlZNASDdENr-7svWtOOpvis8VmKmtl8lXxL_ulkKab9Lruv1flS2-2v0LWIuNhG_0uzf0l6Q8Rt2ItS3RAXsxVhqNxDpCHtY2c9tp4liP8P50cDWXviB4UXHzdBpSf6m7CMR8tZnJvC94S9G1w7fcl3HIKw"
}

Response

The string in the token field is a JWT and it has the following structure:

{
  "header": {
    "alg": "PS512",
    "jku": <JSON_Web_Key_Set_URL>,
    "kid": <key_identifier>,
    "typ": "JWT"
  },
  "payload": {
    "preauthorization_code": <SST>
  },
  "signature": <signed_with_services_private_key>
}

The preauthorization_code is then passed into the digi.me client in exchange for an authorization_code

Response Errors

Subject to Application, Contract, General and OAuth related errors.

Clone this wiki locally