right logo image
right logo image
Log on
⯆

API Explorer

Log off

v5.1.0 (505 APIs)

API Host: https://api3.openbankproject.com
Bank
Accounts
Views
Counterparties
Transactions

Create (DAuth) User with Account Access

This endpoint is used as part of the DAuth solution to grant access to account and transaction data to a smart contract on the blockchain.

Put the smart contract address in username

For provider use "dauth"

This endpoint will create the (DAuth) User with username and provider if the User does not already exist.

Authentication is Mandatory and the logged in user needs to be account holder.

For information about DAuth see below:

DAuth

DAuth Introduction, Setup and Usage

DAuth is an experimental authentication mechanism that aims to pin an ethereum or other blockchain Smart Contract to an OBP "User".

In the future, it might be possible to be more specific and pin specific actors (wallets) that are acting within the smart contract, but so far, one smart contract acts on behalf of one User.

Thus, if a smart contract "X" calls the OBP API using the DAuth header, OBP will get or create a user called X and the call will proceed in the context of that User "X".

DAuth is invoked by the REST client (caller) including a specific header (see step 3 below) in any OBP REST call.

When OBP receives the DAuth token, it creates or gets a User with a username based on the smart_contract_address and the provider based on the network_name. The combination of username and provider is unique in OBP.

If you are calling OBP-API via an API3 Airnode, the Airnode will take care of constructing the required header.

When OBP detects a DAuth header / token it first checks if the Consumer is allowed to make such a call. OBP will validate the Consumer ip address and signature etc.

Note: The DAuth flow does not require an explicit POST like Direct Login to create the token.

Permissions may be assigned to an OBP User at any time, via the UserAuthContext, Views, Entitlements to Roles or Consents.

Note: DAuth is enabled.

Note: The DAuth client is responsible for creating a token which will be trusted by OBP absolutely!

To use DAuth:

1) Configure OBP API to accept DAuth.

Set up properties in your props file

# -- DAuth --------------------------------------
# Define secret used to validate JWT token
# jwt.public_key_rsa=path-to-the-pem-file
# Enable/Disable DAuth communication at all
# In case isn't defined default value is false
# allow_dauth=false
# Define comma separated list of allowed IP addresses
# dauth.host=127.0.0.1
# -------------------------------------- DAuth--

Please keep in mind that property jwt.public_key_rsa is used to validate JWT token to check it is not changed or corrupted during transport.

2) Create / have access to a JWT

The following videos are available:
* DAuth in local environment

HEADER:ALGORITHM & TOKEN TYPE

{
  "alg": "RS256",
  "typ": "JWT"
}

PAYLOAD:DATA

{
  "smart_contract_address": "0xe123425E7734CE288F8367e1Bb143E90bb3F051224",
  "network_name": "AIRNODE.TESTNET.ETHEREUM",
  "msg_sender": "0xe12340927f1725E7734CE288F8367e1Bb143E90fhku767",
  "consumer_key": "0x1234a4ec31e89cea54d1f125db7536e874ab4a96b4d4f6438668b6bb10a6adb",
  "timestamp": "2021-11-04T14:13:40Z",
  "request_id": "0Xe876987694328763492876348928736497869273649"
}

VERIFY SIGNATURE

RSASHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),

) your-RSA-key-pair

Here is an example token:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzbWFydF9jb250cmFjdF9hZGRyZXNzIjoiMHhlMTIzNDI1RTc3MzRDRTI4OEY4MzY3ZTFCYjE0M0U5MGJiM0YwNTEyMjQiLCJuZXR3b3JrX25hbWUiOiJFVEhFUkVVTSIsIm1zZ19zZW5kZXIiOiIweGUxMjM0MDkyN2YxNzI1RTc3MzRDRTI4OEY4MzY3ZTFCYjE0M0U5MGZoa3U3NjciLCJjb25zdW1lcl9rZXkiOiIweDEyMzRhNGVjMzFlODljZWE1NGQxZjEyNWRiNzUzNmU4NzRhYjRhOTZiNGQ0ZjY0Mzg2NjhiNmJiMTBhNmFkYiIsInRpbWVzdGFtcCI6IjIwMjEtMTEtMDRUMTQ6MTM6NDBaIiwicmVxdWVzdF9pZCI6IjBYZTg3Njk4NzY5NDMyODc2MzQ5Mjg3NjM0ODkyODczNjQ5Nzg2OTI3MzY0OSJ9.XSiQxjEVyCouf7zT8MubEKsbOBZuReGVhnt9uck6z6k

3) Try a REST call using the header

Using your favorite http client:

GET https://api3.openbankproject.com/obp/v3.0.0/users/current

Body

Leave Empty!

Headers:

   DAuth: your-jwt-from-step-above

Here is it all together:

GET https://api3.openbankproject.com/obp/v3.0.0/users/current HTTP/1.1
Host: localhost:8080
User-Agent: curl/7.47.0
Accept: /
DAuth: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzbWFydF9jb250cmFjdF9hZGRyZXNzIjoiMHhlMTIzNDI1RTc3MzRDRTI4OEY4MzY3ZTFCYjE0M0U5MGJiM0YwNTEyMjQiLCJuZXR3b3JrX25hbWUiOiJFVEhFUkVVTSIsIm1zZ19zZW5kZXIiOiIweGUxMjM0MDkyN2YxNzI1RTc3MzRDRTI4OEY4MzY3ZTFCYjE0M0U5MGZoa3U3NjciLCJjb25zdW1lcl9rZXkiOiIweDEyMzRhNGVjMzFlODljZWE1NGQxZjEyNWRiNzUzNmU4NzRhYjRhOTZiNGQ0ZjY0Mzg2NjhiNmJiMTBhNmFkYiIsInRpbWVzdGFtcCI6IjIwMjEtMTEtMDRUMTQ6MTM6NDBaIiwicmVxdWVzdF9pZCI6IjBYZTg3Njk4NzY5NDMyODc2MzQ5Mjg3NjM0ODkyODczNjQ5Nzg2OTI3MzY0OSJ9.XSiQxjEVyCouf7zT8MubEKsbOBZuReGVhnt9uck6z6k

CURL example

curl -v -H 'DAuth: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzbWFydF9jb250cmFjdF9hZGRyZXNzIjoiMHhlMTIzNDI1RTc3MzRDRTI4OEY4MzY3ZTFCYjE0M0U5MGJiM0YwNTEyMjQiLCJuZXR3b3JrX25hbWUiOiJFVEhFUkVVTSIsIm1zZ19zZW5kZXIiOiIweGUxMjM0MDkyN2YxNzI1RTc3MzRDRTI4OEY4MzY3ZTFCYjE0M0U5MGZoa3U3NjciLCJjb25zdW1lcl9rZXkiOiIweDEyMzRhNGVjMzFlODljZWE1NGQxZjEyNWRiNzUzNmU4NzRhYjRhOTZiNGQ0ZjY0Mzg2NjhiNmJiMTBhNmFkYiIsInRpbWVzdGFtcCI6IjIwMjEtMTEtMDRUMTQ6MTM6NDBaIiwicmVxdWVzdF9pZCI6IjBYZTg3Njk4NzY5NDMyODc2MzQ5Mjg3NjM0ODkyODczNjQ5Nzg2OTI3MzY0OSJ9.XSiQxjEVyCouf7zT8MubEKsbOBZuReGVhnt9uck6z6k' https://api3.openbankproject.com/obp/v3.0.0/users/current

You should receive a response like:

{
    "user_id": "4c4d3175-1e5c-4cfd-9b08-dcdc209d8221",
    "email": "",
    "provider_id": "0xe123425E7734CE288F8367e1Bb143E90bb3F051224",
    "provider": "ETHEREUM",
    "username": "0xe123425E7734CE288F8367e1Bb143E90bb3F051224",
    "entitlements": {
        "list": []
    }
}

Under the hood

The file, dauth.scala handles the DAuth,

We:

-> Check if Props allow_dauth is true
  -> Check if DAuth header exists
    -> Check if getRemoteIpAddress is OK
      -> Look for "token"
        -> parse the JWT token and getOrCreate the user
          -> get the data of the user

More information

Parameter names and values are case sensitive.
Each parameter MUST NOT appear more than once per request.


URL Parameters:

ACCOUNT_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

BANK_ID: gh.29.uk

JSON request body fields:

is_system: true

provider: ETHEREUM

username: felixsmith

view_id: owner

views:

JSON response body fields:

alias:

can_add_comment:

can_add_corporate_location:

can_add_counterparty: true

can_add_image:

can_add_image_url: true

can_add_more_info: true

can_add_open_corporates_url:

can_add_physical_location:

can_add_private_alias:

can_add_public_alias:

can_add_tag: true

can_add_transaction_request_to_any_account:

can_add_transaction_request_to_own_account:

can_add_url:

can_add_where_tag:

can_create_direct_debit: true

can_create_standing_order:

can_delete_comment:

can_delete_corporate_location: true

can_delete_image: true

can_delete_physical_location:

can_delete_tag:

can_delete_where_tag: true

can_edit_owner_comment: true

can_query_available_funds: true

can_see_bank_account_balance:

can_see_bank_account_bank_name: true

can_see_bank_account_credit_limit: true

can_see_bank_account_currency:

can_see_bank_account_iban:

can_see_bank_account_label: true

can_see_bank_account_national_identifier:

can_see_bank_account_number: true

can_see_bank_account_owners: true

can_see_bank_account_routing_address:

can_see_bank_account_routing_scheme:

can_see_bank_account_swift_bic:

can_see_bank_account_type:

can_see_bank_routing_address: true

can_see_bank_routing_scheme:

can_see_comments:

can_see_corporate_location: true

can_see_image_url: true

can_see_images: true

can_see_more_info:

can_see_open_corporates_url:

can_see_other_account_bank_name:

can_see_other_account_iban:

can_see_other_account_kind:

can_see_other_account_metadata:

can_see_other_account_national_identifier: true

can_see_other_account_number: true

can_see_other_account_routing_address: true

can_see_other_account_routing_scheme:

can_see_other_account_swift_bic: true

can_see_other_bank_routing_address:

can_see_other_bank_routing_scheme:

can_see_owner_comment:

can_see_physical_location:

can_see_private_alias:

can_see_public_alias:

can_see_tags:

can_see_transaction_amount: true

can_see_transaction_balance:

can_see_transaction_currency:

can_see_transaction_description: true

can_see_transaction_finish_date:

can_see_transaction_metadata:

can_see_transaction_other_bank_account:

can_see_transaction_start_date:

can_see_transaction_this_bank_account:

can_see_transaction_type:

can_see_url: true

can_see_where_tag: true

description: This an optional field. Maximum length is 2000. It can be any characters here.

hide_metadata_if_alias_used:

id: d8839721-ad8f-45dd-9f78-2080414b93f9

is_public: true

is_system: true

metadata_view:

short_name:

is_firehose:

Typical Successful Response: 

								
									
[{
  "id":"1234",
  "short_name":"short_name",
  "description":"description",
  "metadata_view":"owner",
  "is_public":true,
  "is_system":true,
  "alias":"No",
  "hide_metadata_if_alias_used":true,
  "can_add_comment":true,
  "can_add_corporate_location":true,
  "can_add_image":true,
  "can_add_image_url":true,
  "can_add_more_info":true,
  "can_add_open_corporates_url":true,
  "can_add_physical_location":true,
  "can_add_private_alias":true,
  "can_add_public_alias":true,
  "can_add_tag":true,
  "can_add_url":true,
  "can_add_where_tag":true,
  "can_delete_comment":true,
  "can_add_counterparty":true,
  "can_delete_corporate_location":true,
  "can_delete_image":true,
  "can_delete_physical_location":true,
  "can_delete_tag":true,
  "can_delete_where_tag":true,
  "can_edit_owner_comment":true,
  "can_see_bank_account_balance":true,
  "can_query_available_funds":true,
  "can_see_bank_account_bank_name":true,
  "can_see_bank_account_currency":true,
  "can_see_bank_account_iban":true,
  "can_see_bank_account_label":true,
  "can_see_bank_account_national_identifier":true,
  "can_see_bank_account_number":true,
  "can_see_bank_account_owners":true,
  "can_see_bank_account_swift_bic":true,
  "can_see_bank_account_type":true,
  "can_see_comments":true,
  "can_see_corporate_location":true,
  "can_see_image_url":true,
  "can_see_images":true,
  "can_see_more_info":true,
  "can_see_open_corporates_url":true,
  "can_see_other_account_bank_name":true,
  "can_see_other_account_iban":true,
  "can_see_other_account_kind":true,
  "can_see_other_account_metadata":true,
  "can_see_other_account_national_identifier":true,
  "can_see_other_account_number":true,
  "can_see_other_account_swift_bic":true,
  "can_see_owner_comment":true,
  "can_see_physical_location":true,
  "can_see_private_alias":true,
  "can_see_public_alias":true,
  "can_see_tags":true,
  "can_see_transaction_amount":true,
  "can_see_transaction_balance":true,
  "can_see_transaction_currency":true,
  "can_see_transaction_description":true,
  "can_see_transaction_finish_date":true,
  "can_see_transaction_metadata":true,
  "can_see_transaction_other_bank_account":true,
  "can_see_transaction_start_date":true,
  "can_see_transaction_this_bank_account":true,
  "can_see_transaction_type":true,
  "can_see_url":true,
  "can_see_where_tag":true,
  "can_see_bank_routing_scheme":true,
  "can_see_bank_routing_address":true,
  "can_see_bank_account_routing_scheme":true,
  "can_see_bank_account_routing_address":true,
  "can_see_other_bank_routing_scheme":true,
  "can_see_other_bank_routing_address":true,
  "can_see_other_account_routing_scheme":true,
  "can_see_other_account_routing_address":true,
  "can_add_transaction_request_to_own_account":true,
  "can_add_transaction_request_to_any_account":true,
  "can_see_bank_account_credit_limit":true,
  "can_create_direct_debit":true,
  "can_create_standing_order":true
}]
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-20047: User must have access to the owner view or must be an account holder.
  • OBP-10001: Incorrect json format.
  • OBP-30252: System view not found. Please specify a valid value for VIEW_ID
  • OBP-30005: View not found for Account. Please specify a valid value for VIEW_ID
  • OBP-30063: Cannot grant account access.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv4.0.0, function_name: by createUserWithAccountAccess, operation_id: OBPv4.0.0-createUserWithAccountAccess Tags: Account-Access, View-Custom, Account, User, OwnerViewRequired, DAuth,

Grant User access to View

Grants the User identified by USER_ID access to the view identified by VIEW_ID.

Authentication is Mandatory and the user needs to be account holder.

URL Parameters:

ACCOUNT_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

BANK_ID: gh.29.uk

JSON request body fields:

is_system: true

user_id: 9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1

view:

view_id: owner

JSON response body fields:

alias:

can_add_comment:

can_add_corporate_location:

can_add_counterparty: true

can_add_image:

can_add_image_url: true

can_add_more_info: true

can_add_open_corporates_url:

can_add_physical_location:

can_add_private_alias:

can_add_public_alias:

can_add_tag: true

can_add_transaction_request_to_any_account:

can_add_transaction_request_to_own_account:

can_add_url:

can_add_where_tag:

can_create_direct_debit: true

can_create_standing_order:

can_delete_comment:

can_delete_corporate_location: true

can_delete_image: true

can_delete_physical_location:

can_delete_tag:

can_delete_where_tag: true

can_edit_owner_comment: true

can_query_available_funds: true

can_see_bank_account_balance:

can_see_bank_account_bank_name: true

can_see_bank_account_credit_limit: true

can_see_bank_account_currency:

can_see_bank_account_iban:

can_see_bank_account_label: true

can_see_bank_account_national_identifier:

can_see_bank_account_number: true

can_see_bank_account_owners: true

can_see_bank_account_routing_address:

can_see_bank_account_routing_scheme:

can_see_bank_account_swift_bic:

can_see_bank_account_type:

can_see_bank_routing_address: true

can_see_bank_routing_scheme:

can_see_comments:

can_see_corporate_location: true

can_see_image_url: true

can_see_images: true

can_see_more_info:

can_see_open_corporates_url:

can_see_other_account_bank_name:

can_see_other_account_iban:

can_see_other_account_kind:

can_see_other_account_metadata:

can_see_other_account_national_identifier: true

can_see_other_account_number: true

can_see_other_account_routing_address: true

can_see_other_account_routing_scheme:

can_see_other_account_swift_bic: true

can_see_other_bank_routing_address:

can_see_other_bank_routing_scheme:

can_see_owner_comment:

can_see_physical_location:

can_see_private_alias:

can_see_public_alias:

can_see_tags:

can_see_transaction_amount: true

can_see_transaction_balance:

can_see_transaction_currency:

can_see_transaction_description: true

can_see_transaction_finish_date:

can_see_transaction_metadata:

can_see_transaction_other_bank_account:

can_see_transaction_start_date:

can_see_transaction_this_bank_account:

can_see_transaction_type:

can_see_url: true

can_see_where_tag: true

description: This an optional field. Maximum length is 2000. It can be any characters here.

hide_metadata_if_alias_used:

id: d8839721-ad8f-45dd-9f78-2080414b93f9

is_public: true

is_system: true

metadata_view:

short_name:

is_firehose:

Typical Successful Response: 

								
									
{
  "id":"1234",
  "short_name":"short_name",
  "description":"description",
  "metadata_view":"owner",
  "is_public":true,
  "is_system":true,
  "alias":"No",
  "hide_metadata_if_alias_used":true,
  "can_add_comment":true,
  "can_add_corporate_location":true,
  "can_add_image":true,
  "can_add_image_url":true,
  "can_add_more_info":true,
  "can_add_open_corporates_url":true,
  "can_add_physical_location":true,
  "can_add_private_alias":true,
  "can_add_public_alias":true,
  "can_add_tag":true,
  "can_add_url":true,
  "can_add_where_tag":true,
  "can_delete_comment":true,
  "can_add_counterparty":true,
  "can_delete_corporate_location":true,
  "can_delete_image":true,
  "can_delete_physical_location":true,
  "can_delete_tag":true,
  "can_delete_where_tag":true,
  "can_edit_owner_comment":true,
  "can_see_bank_account_balance":true,
  "can_query_available_funds":true,
  "can_see_bank_account_bank_name":true,
  "can_see_bank_account_currency":true,
  "can_see_bank_account_iban":true,
  "can_see_bank_account_label":true,
  "can_see_bank_account_national_identifier":true,
  "can_see_bank_account_number":true,
  "can_see_bank_account_owners":true,
  "can_see_bank_account_swift_bic":true,
  "can_see_bank_account_type":true,
  "can_see_comments":true,
  "can_see_corporate_location":true,
  "can_see_image_url":true,
  "can_see_images":true,
  "can_see_more_info":true,
  "can_see_open_corporates_url":true,
  "can_see_other_account_bank_name":true,
  "can_see_other_account_iban":true,
  "can_see_other_account_kind":true,
  "can_see_other_account_metadata":true,
  "can_see_other_account_national_identifier":true,
  "can_see_other_account_number":true,
  "can_see_other_account_swift_bic":true,
  "can_see_owner_comment":true,
  "can_see_physical_location":true,
  "can_see_private_alias":true,
  "can_see_public_alias":true,
  "can_see_tags":true,
  "can_see_transaction_amount":true,
  "can_see_transaction_balance":true,
  "can_see_transaction_currency":true,
  "can_see_transaction_description":true,
  "can_see_transaction_finish_date":true,
  "can_see_transaction_metadata":true,
  "can_see_transaction_other_bank_account":true,
  "can_see_transaction_start_date":true,
  "can_see_transaction_this_bank_account":true,
  "can_see_transaction_type":true,
  "can_see_url":true,
  "can_see_where_tag":true,
  "can_see_bank_routing_scheme":true,
  "can_see_bank_routing_address":true,
  "can_see_bank_account_routing_scheme":true,
  "can_see_bank_account_routing_address":true,
  "can_see_other_bank_routing_scheme":true,
  "can_see_other_bank_routing_address":true,
  "can_see_other_account_routing_scheme":true,
  "can_see_other_account_routing_address":true,
  "can_add_transaction_request_to_own_account":true,
  "can_add_transaction_request_to_any_account":true,
  "can_see_bank_account_credit_limit":true,
  "can_create_direct_debit":true,
  "can_create_standing_order":true
}
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-20047: User must have access to the owner view or must be an account holder.
  • OBP-10001: Incorrect json format.
  • OBP-20005: User not found. Please specify a valid value for USER_ID.
  • OBP-30252: System view not found. Please specify a valid value for VIEW_ID
  • OBP-30005: View not found for Account. Please specify a valid value for VIEW_ID
  • OBP-30063: Cannot grant account access.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv4.0.0, function_name: by grantUserAccessToView, operation_id: OBPv4.0.0-grantUserAccessToView Tags: Account-Access, View-Custom, Account, User, OwnerViewRequired,

Revoke User access to View

Revoke the User identified by USER_ID access to the view identified by VIEW_ID.

Authentication is Mandatory and the user needs to be account holder.

URL Parameters:

ACCOUNT_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

BANK_ID: gh.29.uk

JSON request body fields:

is_system: true

user_id: 9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1

view:

view_id: owner

JSON response body fields:

revoked:

Typical Successful Response: 

								
									
{
  "revoked":true
}
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-20047: User must have access to the owner view or must be an account holder.
  • OBP-10001: Incorrect json format.
  • OBP-20005: User not found. Please specify a valid value for USER_ID.
  • OBP-30252: System view not found. Please specify a valid value for VIEW_ID
  • OBP-30005: View not found for Account. Please specify a valid value for VIEW_ID
  • OBP-30064: Cannot revoke account access.
  • OBP-30065: Cannot find account access.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv4.0.0, function_name: by revokeUserAccessToView, operation_id: OBPv4.0.0-revokeUserAccessToView Tags: Account-Access, View-Custom, Account, User, OwnerViewRequired,

Revoke/Grant User access to View

Revoke/Grant the logged in User access to the views identified by json.

Authentication is Mandatory and the user needs to be an account holder or has owner view access.

URL Parameters:

ACCOUNT_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

BANK_ID: gh.29.uk

JSON response body fields:

revoked:

Typical Successful Response: 

								
									
{
  "revoked":true
}
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-20047: User must have access to the owner view or must be an account holder.
  • OBP-10001: Incorrect json format.
  • OBP-20005: User not found. Please specify a valid value for USER_ID.
  • OBP-30252: System view not found. Please specify a valid value for VIEW_ID
  • OBP-30005: View not found for Account. Please specify a valid value for VIEW_ID
  • OBP-30064: Cannot revoke account access.
  • OBP-30065: Cannot find account access.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv4.0.0, function_name: by revokeGrantUserAccessToViews, operation_id: OBPv4.0.0-revokeGrantUserAccessToViews Tags: Account-Access, View-Custom, Account, User, OwnerViewRequired,