Authorization Flows

In the request examples below, {{urlSensedia}} is the address of your company’s Sensedia environment (i.e., the address of your API Manager).

Resource: /register

{{urlSensedia}}/jans-auth/register

This resource is used to register and manage the record of institutions as clients at Sensedia (i.e., applications with access to the business APIs in the context of Open Banking).

POST

POST {{urlSensedia}}/jans-auth/register

Operation to register a client.

Include the header:

Content-Type: application/json

In the body, pass these items:

software_statement: information obtained from the Central Bank when the institution is registered as an Open Banking participant.
tls_client_auth_subject_dn: DN of the client’s transport certificate.
redirect_uris: include all redirects that the client can use in the flow authorize.

Example of body:

{
 "redirect_uris": [
   "https://api-testing.sensedia.com/opb-mock"
 ],
 "tls_client_auth_subject_dn": "EMAILADDRESS=opb@sensedia.com,CN=c98f9eaf-eba5-4b7a-ac43-d9edf9395076,OU=OpenBanking,O=Sensedia,L=Campinas,ST=SP,C=BR",
 "software_statement": "eyJraWQiOiJvcGVuYmFua2luZyIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJzb2Z0d2FyZV9tb2RlIjoiTGl2ZSIsInNvZnR3YXJlX3JlZGlyZWN0X3VyaXMiOlsiaHR0cHM6Ly9hcGktdGVzdGluZy5zZW5zZWRpYS5jb20vbW9hY3lyLW1vY2siXSwic29mdHdhcmVfc3RhdGVtZW50X3JvbGVzIjpbeyJyb2xlIjoiREFET1MiLCJhdXRob3Jpc2F0aW9uX2RvbWFpbiI6Ik9wZW4gQmFua2luZyIsInN0YXR1cyI6IkFjdGl2ZSJ9XSwic29mdHdhcmVfY2xpZW50X25hbWUiOiJDYXN0ZWxsbyBUUFAiLCJvcmdfc3RhdHVzIjoiQWN0aXZlIiwic29mdHdhcmVfY2xpZW50X2lkIjoiYzk4ZjllYWYtZWJhNS00YjdhLWFjNDMtZDllZGY5Mzk1MDc2IiwiaXNzIjoiT3BlbiBCYW5raW5nIEJyYXNpbCIsInNvZnR3YXJlX2p3a3NfdXJpIjoiaHR0cHM6Ly9hcGktdGVzdGluZy5zZW5zZWRpYS5jb20vaGFuZGxlcnMvdjEvandrcyIsInNvZnR3YXJlX3BvbGljeV91cmkiOiJodHRwczovL3d3dy5zZW5zZWRpYS5jb20iLCJzb2Z0d2FyZV9pZCI6ImM5OGY5ZWFmLWViYTUtNGI3YS1hYzQzLWQ5ZWRmOTM5NTA3NiIsInNvZnR3YXJlX3N0YXRlbWVudF9pZCI6ImM5OGY5ZWFmLWViYTUtNGI3YS1hYzQzLWQ5ZWRmOTM5NTA3NiIsInNvZnR3YXJlX2NsaWVudF91cmkiOiJodHRwczovL3d3dy5zZW5zZWRpYS5jb20vc2Vuc2VkaWEtY2FyZWVyIiwic29mdHdhcmVfbG9nb191cmkiOiJodHRwczovL3d3dy5zZW5zZWRpYS5jb20vbG9nby5wbmciLCJvcmdfaWQiOiJiOTYxYzRlYi01MDlkLTRlZGYtYWZlYi0zNTY0MmIzODE4NWQiLCJzb2Z0d2FyZV9lbnZpcm9ubWVudCI6InByb2R1Y3Rpb24iLCJzb2Z0d2FyZV92ZXJzaW9uIjoxLjEsInNvZnR3YXJlX3JvbGVzIjpbIkRBRE9TIl0sIm9yZ19uYW1lIjoiT3BlbiBCYW5raW5nIEJyYXNpbCIsImlhdCI6MTYxODMzNjI2Miwib3JnYW5pc2F0aW9uX2NvbXBldGVudF9hdXRob3JpdHlfY2xhaW1zIjpbeyJhdXRob3Jpc2F0aW9uX2RvbWFpbiI6Ik9wZW4gQmFua2luZyIsImF1dGhvcmlzYXRpb25zIjpbXSwicmVnaXN0cmF0aW9uX2lkIjoiMTMzNTMyMzYtT0JCLURBRE9TIiwiYXV0aG9yaXR5X2lkIjoiNjg3YTFjOTQtYjM2MC00ZTA0LTk1ODktMGZhNWNiMTY0NTFiIiwiYXV0aG9yaXNhdGlvbl9yb2xlIjoiREFET1MiLCJhdXRob3JpdHlfY29kZSI6IkJDQiIsInN0YXR1cyI6IkFjdGl2ZSJ9XX0.Ze_yXEOxR3_EnIzwni5wdaYphQQxV6UYDKWIyceMwbKrA1k5i7hJXDrGg_7fXgKpSd1mqCtdJPfRgmYxLYjp0_UXIUHTC_u2wdMX-2rLj_GtV-jAkSdu55h4PWkHfBEKTdbh9aZEUZivBbjL_X-vSJ1DJNQXEAadSso4hgM1AWux8CG9qFOlmJ2R8tS1PeybqbXNxDPy5fVM0uXk37P27Ur56RuawLdIknkfSVrpLurEacLnY6pmOiC4STwehbR8EqlNLTTYYwwPVKyBmLrnaYBqnpaGFYb5jBXEYrhGoBKQqWsL3UF_en5gmE7xRFmFP0-07TOa_KvmyWN3RepR0w"
}

The response must contain: registration_access_token, client_secret and client_id, used in other requests described here.

GET

GET {{urlSensedia}}/jans-auth/register?client_id={{client_id}}

Operation to retrieve data regarding a client’s registration at Sensedia.

Include the header:

Authorization: Bearer {{registration_access_token}}

This registration_access_token is received in the POST /register call described above.

PUT

PUT {{urlSensedia}}/jans-auth/register?client_id={{client_id}}

Operation to change data from a client’s registration at Sensedia. The modified information must be included in the body in JSON format.

Include the header:

Authorization: Bearer {{registration_access_token}}

This registration_access_token is received in the POST /register call described above.

DELETE

Operation to completely delete a client’s registration at Sensedia.

Include the header:

Authorization: Bearer {{registration_access_token}}

This registration_access_token is received in the POST /register call described above.

Resources for tokens

Resources to generate, revoke, and view details of tokens.

/token: Client Credentials flow

POST {{urlSensedia}}/jans-auth/token

Operation to generate a token.

Include the header:

Content-type: application/x-www-form-urlencoded

In the body, include the following data (in the format x-www-form-urlencoded):

grant_type: the flow used to generate the token, which must be client_credentials.
client_id: received in the POST /register call described above.
client_secret: received in the POST /register call described above.
scope: scope under which the access token will be used (to create consent: consents).

Example of body:

grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}&scope=consents

/token: Authorization Code flow

POST {{urlSensedia}}/jans-auth/token

Operation to generate a token. In the call, a code is exchanged for a token — the code passed in the request is received when the user who owns the data performs the authentication and authorization at the institution that holds the data.

Include the header:

Content-type: application/x-www-form-urlencoded

In the body, include the following data (in the format x-www-form-urlencoded):

grant_type: the flow used to generate the token, which must be authorization_code.
client_id: received in the POST /register call described above.
scope: scope under which the access token will be used (example: for payments, use openid payments).
code: code received when the user is authenticated and authorized at the institution that holds the data.
redirect-uri: where the flow should go back to after user authentication and authorization.

Example of body:

grant_type=authorization_code&client_id={{client_id}}&scope=openid payments&code=37305ff2-c4bc-4053-b8fe-7e4b2bda0deb&redirect_uri=https://api-testing.sensedia.com/mock

The response will include an access token (which will grant access to the business APIs), info on the token’s expiration time and a refresh token (which can be used to update the token after it expires).

/token: Refresh Token flow

POST {{urlSensedia}}/jans-auth/token

Operation to update an expired token.

Include the header:

Content-type: application/x-www-form-urlencoded

In the body, include the following data (in the format x-www-form-urlencoded):

grant_type: the flow used to generate the token, which must be refresh_token.
client_id: received in the POST /register call described above.
refresh_token: received in the call that generated the original token.

Example of body:

grant_type=refresh_token&client_id={{client_id}}&refresh_token={{refresh_token}}

/revoke: token revocation

POST {{urlSensedia}}/jans-auth/revoke

Revocation renders unusable a token that is still valid but no longer needed. You can revoke both an access token or a refresh token. In both cases, all tokens are revoked — that is, if you revoke an access token and there is a refresh token associated with it, it is also revoked, and if you revoke a refresh token, the access token associated with it is also revoked.

Include the header Authorization:

Authorization: Bearer {{access_token}}

In the body, include the following data (in the format x-www-form-urlencoded):

token={{access_token}}>&token_type_hint=access_token

token={{refresh_token}}&token_type_hint=refresh_token

Note that the token_type_hint is not required (because the token is found by the value entered), but it does make the revocation operation faster.

/introspection: token details

POST {{urlSensedia}}/jans-auth/introspection
GET {{urlSensedia}}/jans-auth/introspection?token={{access_token}}

Resource to retrieve information on a token.

If using the GET operation (with a token value as parameter), include the header Authorization:

Authorization: Bearer {{access_token}}

If using the POST operation, include the same header Authorization as above and also:

Content-type: application/x-www-form-urlencoded

In the body of the POST request, include:

token={{access_token}}

Resource: /authorize

Resource used for the institution requesting the data to receive the redirect so that the user goes to the transmitter’s login screen.

It is possible to make a POST or GET operation with the same purpose. What changes is the way the data is sent in the request (in the POST operation, the data is sent in the body, while the GET request sends the data as parameters).

POST

POST {{urlSensedia}}/jans-auth/authorize

Include the header:

Content-type: application/x-www-form-urlencoded

In the body, include the following data (in the format x-www-form-urlencoded):

client_id: received in the POST /register call described above.
redirect-uri: where the flow should go back to after user authentication and authorization.
request: an OpenID Connect Request object as defined in the OpenID Connect Core.
scope: scope under which the access token will be used (example: for payments, use openid payments).
response_type: include the value code.

Example of body:

client_id={{client_id}}&redirect_uri=https://api-testing.sensedia.com/mock&request=eyJraWQiOiJvcGVuYmFua2luZyIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJjOThmOWVhZi1lYmE1LTRiN2EtYWM0My1kOWVkZjkzOTUwNzYiLCJyZXNwb25zZV90eXBlIjoiY29kZSIsIm5vbmNlIjoiNFNvNHJhTk9SMEdOMjJsNFB1SEdwTkg0MUZmNk1JZ05rc3lpS2FPRkQ0byIsImNsaWVudF9pZCI6ImM5OGY5ZWFmLWViYTUtNGI3YS1hYzQzLWQ5ZWRmOTM5NTA3NiIsImF1ZCI6Imh0dHBzOi8vb3BlbmJhbmtpbmctcHVibGljLXRlc3Rpbmcuc2Vuc2VkaWEuY29tIiwic2NvcGUiOiJjb25zZW50cyBvcGVuaWQiLCJjbGFpbXMiOnsiaWRfdG9rZW4iOnsib3BlbmJhbmtpbmdfaW50ZW50X2lkIjp7InZhbHVlIjoiYmNjZTdlYmQtMmJiZS00NDFhLTgxN2UtNDMwMjEyMWFjMjQxIiwiZXNzZW50aWFsIjp0cnVlfX19LCJyZWRpcmVjdF91cmkiOiJodHRwczovL2FwaS10ZXN0aW5nLnNlbnNlZGlhLmNvbS9tb2FjeXItbW9jayIsInN0YXRlIjoiY2FzdGVsbG8iLCJleHAiOjE2MTg1NjY3MzksImlhdCI6MTYxODU2MTMzOSwianRpIjoiZjJhYjljNzQtNWMyOC00OGYwLTkzZmItNmUyNjU1NWQwZGJkIn0.FyJBqp3ZC-KgUCaBCoQ_7AWJAi2zPuznOId-CCFjT5u5DRJhvFvFoRFE2In2JQuEfE5tifV0CthCSPP-XuQF1amN8w4InLOWXxsOxVC350fhs2KVHC7SB6wD2NJKpCUdciIIyyckRPF56Jp1xFi4elEhe4ToUDsUK49MVM3FQOCfdKQNVI6TWkfqsZmEEFxGdmyeh6WnrQ2k61DVb2LUEkDoYjI210dhqQNHnqUEdUjYVKSIQaNPW4iidegGZygra_z09A0SsaV1Z5t-TGMvT5cSEVCnd-l_YXvqXEgamqu10kAFEuZiS9cQp_LLbcPRYcgYuCFXmpNrMkzqXJwXzA&scope=openid payments&response_type=code

GET

GET {{urlSensedia}}/jans-auth/authorize?{{params}}

Send the following data as query params:

client_id: received in the POST /register call described above.
request: an OpenID Connect Request object as defined in the OpenID Connect Core.
scope: scope under which the access token will be used (example: for payments, use openid payments).
response_type: include the value code.

Resource: /well-known

GET {{urlSensedia}}/.well-known/openid-configuration

Resource to retrieve data on our Authorization Server — endpoints and what we offer as a security model.

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]