Token

Exchanging for an access token

We can use this endpoint to retrieve a new access token. There are two scenarios when this can be used:

1. Once you've got an authorization code, you can exchange it for an access token.
2. An access token has expired and you have a refresh token to get a new one.

POST /v1.6/oauth/token

Request Header

Parameter	Required	Description	Type
Accept	Yes	The content types, expressed as MIME types, the client is able to understand. Use application/json.	string
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
Content-Type	Yes	Indicate the media type of the resource. Use application/json.	string

The payload for the Authorization JWT when exchanging an authorization code for an access token:

{
  "client_id": <appId_contractId>,
  "code": <authorization_code>,
  "code_verifier": <code_verifier>,
  "grant_type": "authorization_code",
  "nonce": <^[a-zA-Z0-9]{32}$>,
  "redirect_uri": <registered_redirect_uri>,
  "timestamp": <current_unix_time>
}

Property	Required	Description	Data type
client_id	Yes	A string consisting of the application ID and contract ID separated by an underscore. ie appId_contractId	string
code	Yes	Authorization code.	string
code_verifier	Yes	The code verifier that was created in the preauthorization process.	string
grant_type	Yes	Pass authorization_code if you're exchanging a code for an access token.	string
nonce	Yes	A 32-char string made up of random alphanumeric characters.	string
redirect_uri	Yes	The redirect URL that's been registered to your digi.me contract.	string
timestamp	Yes	Unix timestamp in seconds.	number

The payload for the Authorization JWT when exchanging a refresh token for an access token:

{
  "client_id": <appId_contractId>,
  "grant_type": "refresh_token",
  "nonce": <^[a-zA-Z0-9]{32}$>,
  "redirect_uri": <registered_redirect_uri>,
  "refresh_token": <refresh_token>,
  "timestamp": <current_unix_time>
}

Property	Required	Description	Data type
client_id	Yes	A string consisting of the application ID and contract ID separated by an underscore. ie appId_contractId	string
grant_type	Yes	Pass refresh_token if you're using a refresh token to retrieve a new access token.	string
nonce	Yes	A 32-char string made up of random alphanumeric characters.	string
redirect_uri	Yes	The redirect URL that's been registered to your digi.me contract.	string
refresh_token	Yes	The refresh token.	string
timestamp	Yes	Unix timestamp in seconds.	number

Sample Request API

curl -i -X POST \
   -H "Content-Type:application/json" \
   -H "Accept:application/json" \
   -H "Authorization:Bearer eyJhbGciOiJQUzUxMiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJJTDdhUFlXTzZEVWFVOWtnWTdad0hwVjFHN0FlQkhRVF9xWWZqR2kwRmdaY01wa1pqekZRMW56NXU3VFg5bEZjWSIsImNvZGUiOiJhMzdkODhhMTI4N2RhM2JmMWViMWRjMDZmNWQxMWI3MGQxZmRiZTQxNDdlNDk3Y2I5NmUyMDk4YmIyOGNjODBkYzEzMzYxMzllNWU3MTIyM2U1NDA2MmNmMWQyOTk2Njk1MzZiODIxN2NjZjc1M2ZiNmJhM2UzODkzMzA0MTY4ZGE4NWZlMWUzYWRiY2I4ZmNjZDIxZTVkNjM2ZGY2YWJhIiwiY29kZV92ZXJpZmllciI6ImJrdGphVk5rWkZsa2VtdGxiMVZQWjI1VWNsTnJla2RNTm1nNVdIVTVhRmsiLCJncmFudF90eXBlIjoiYXV0aG9yaXphdGlvbl9jb2RlIiwibm9uY2UiOiJRSzgybllnZlBLVTlIWXF3b0wxYm5xTXpSSjZYV1FscyIsInJlZGlyZWN0X3VyaSI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODA4MS9jeWNsaWMtcmVzdWx0cyIsInRpbWVzdGFtcCI6MTYwNDY3MzY4NTE4Nn0.gRGAFj9QKQADBbADU0XCXhdncckUlQ1A-euECLW8mk2DxDdjbA3yjmtq3OdGgGSUuSwA5Vz0n_4M6C3L3GqYJILe7tHN9iXtInoC1ygWw-J3lwDZO8prIfkKJ_OrKEOxVcb68GWPs8e1GQUr19-kyCM7S5Gi2607Xvq049EtW02r43-ojJ10tqW02J0VaDQfvfm7Bv8A7ScCBm-9LBhtxYaOy3TDA5KufwzrMXrWl2oIJZ-kxfqPn1pW7ucd7fB-hq9mcD_FJCrzV_NO6KNo9rk2EsbdpYiaGy9slZnCjq3K8JaCgVhXeGlLHCzr_spFXQDxtPpAgm9_C1-Z_1lSKQ" \
 'https://api.digi.me/v1.6/oauth/token'

---

Sample Response API

200 OK
{
  "token": "eyJhbGciOiJQUzUxMiIsImprdSI6Imh0dHA6Ly9sb2NhbGhvc3Q6MzAwMC92MS42L2p3a3Mvb2F1dGgiLCJraWQiOiJodHRwczovL2RpZ2ltZS1hbHBoYS1rZXktdmF1bHQudmF1bHQuYXp1cmUubmV0L2tleXMvb2F1dGgvNWU1ZjhkMDRhOGU1NGNkZTg1MDYyMzBmY2UwYThiZTkiLCJ0eXAiOiJKV1QifQ.eyJhY2Nlc3NfdG9rZW4iOnsiZXhwaXJlc19vbiI6MTY0MDg2NjI0MywidmFsdWUiOiJlYzNjZDFlYWM1YjUyOWMzOWUyNTZjZjkyNGMyMTNiZGJmNGI1MTZkMjU5NDAxZDI1ODc4MTYzZGM1NmE2MDhkZWJiYjFmZmY5ZDg2NjE1YTc1MzNlZWI0ZWI5YzkzZjFlNDU0NTFiZTk1ZDRkMzI4MWUwNjRiNWY1M2M4NjBmNzkzOGI4MDVhMjMwY2RlMDliNTgzYmVhMzkyZWIxMzNlIn0sImNvbnNlbnRpZCI6ImViM2YwNTMwOGQ0NWI1OTEyMmM5NDhiZDIzMGUwNGU0IiwiaWRlbnRpZmllciI6eyJpZCI6ImI1ZTA5M2M2MzAyZTQzOWM2Y2MyZTY3YTc1MmU0YTNlIn0sInJlZnJlc2hfdG9rZW4iOnsiZXhwaXJlc19vbiI6MTY1NjMzMTg0MywidmFsdWUiOiI2NTc4M2NiMDM3ODJjMzAzZDgwMmVkN2ZkOGNmMTFiZDhjOGU1N2UxYWQ5YmZiOGI1MDE1OTExNDFmMjE4OGVkOWRlMzZlNGU4Yjk2MWIzY2NlYzUzZDgzODYzYjRjYzc0MWUzNmRlNGUwMWJjYjU1MTNiODM0ZjYzM2M1ZjQ3Y2JhMTc3MGYxMjY3ZDczNzQ0NjU2ZmI4YmVhZmIxN2M2In0sInRva2VuX3R5cGUiOiJCZWFyZXIifQ.cY8Lw7hJFwXOf6WLtmEzxdyHx_nyBryQRM2H0fSb2CtRULpoEHRbJEdafwWOz92RFSk9eiDIIzxEtFrgQwS9DDiRZclFzpiWS-JR7qIRCO0IgHef2gR4ZhIyvcnypdEF4Z3vCnaII4oXHr0IkQ0WgFYe9dFM_FkSwgBnmDApTIuST2HnpyWSPRPV3O8Zih8XjmA8amLf5tJ3WSseNEueCf167bkcFJ0CgGwU3zLCnuwm76TM6yWrD7B5Psx6EcIVsthWSu6DL34rFIRXdn9p_oDEiZDT73R6Yloi62gDd_Etnocsn6jjyQR9yk3jFQyFor5e_vnYTH3q4FX3beVgIw"
}

Response

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

{
  "header": {
    "alg": "PS512",
    "jku": <JSON_Web_Key_Set_URL>,
    "kid": <key_identifier>,
    "typ": "JWT"
  },
  "payload": {
     {
        access_token: {
          expires_on: <value>,
          value: <access_token>
      },
      consentid: <consent_id>,
      identifier: {
        id: <id>
      },
      refresh_token: {
        expires_on: <value>,
        value: <refresh_token>
      },
      token_type: 'Bearer'
    }
  },
  "signature": <signed_with_services_private_key>
}

Response Definitions

Response item	Description	Data type
access_token	The access token that can be used to request user data.	object
refresh_token	A refresh token that can be used to retrieve a new access token once the current one expires.	object
token_type	Bearer	string
consentid	Consent ID, ie hashSha512(app_id + contract_id + user_id)	string
identifier	Default app user scope, ie hashSha512(user_id + app_id)	object

Response Errors

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