This section describes the practical steps to get up and running in the SpareBank 1 sandbox environment.
Getting started
All of the API's within the portal will respond with data from a closed sandbox environment. We strive to keep the APIs deployed in the sandbox the same as in .production, but minor discrepancies might occur.
Swagger 2.0 definitions can be downloaded for all API's in the developer portal. The SpareBank1 API's uses the OAuth 2.0 protocol to authorize API's in production but this protocol is simplified and mocked in the sandbox. In addition a dummy bank and customer is automatically assigned when generating your Oauth token in the sandbox environment.
How to get started
- Fill inn the form with your name, email, password, confirm password.
- If you have an organization code from an invite, you can fill it in. If not, leave the field blank.
- Read the User Agreement and Cookie Policy. If you agree to the terms you are ready to registrate.
You will receive an email within 3-5 minutes from developer@sparebank1.no. If you don't get this mail you should check your junk-mail folder.
In this mail there is a link called "Activate Account". Press the link, and it will take you to a web-page for the final procedure. Your user is now active and you can sign in to the developer portal.
Sign in with your login name (email) and password chosen during the registration.
Development
1. Create application
- Choose "Applications" from the top menu and press the button "Create application".
- Fill in the mandatory fields (and any optional fields if desired).
- Select the API's you want your application to access. NB! You will not able to test an API that isn't assined to an application.
- Save your application
2. Generate OAuth credentials
A request token is required to send requests to the API's. To generate the token you will first need OAuth credentials for your application.
- Click on your newly created application.
- Click the "Edit application" button.
- Click the "Authentication" tab.
- Expand "OAuth Credentials" and click the "Generate" button. A window called "Generate OAuth Client Credentials" will pop up. For basic testing of the API's within the developer portal just press "Generate Client". An OAuth Client ID is generated and you are ready for testing the API's.
3. Basic testing of an API from the Developer portal
- Click "APIs" from the top menu.
- Click on the API you want to test.
- Choose the OAuth client from the application you created (see drop-down list).
- Click "Request token" and then click "Authorize". This will pass your application's OAuth credentials, along with the end-user's authentication code, to SpareBank1 to issue a bearer token. A bearer token enables you to complete actions on behalf of, and with the approval of, the end-user. The end-user is, as already explained, mocked and static in the sandbox.
- Click the URI you want to test and fill in the parameters needed (if any).
- Scroll down and press "Try it out" to send the request.
- You will then see the response, body and header.
4. Invoke an API outside the developer portal
The SpareBank 1 APIs are HTTP-based RESTful APIs, using JSON-formatted requests and response bodies.
5. Issue an OAuth token
To issue an OAuth Token do a request to https://developer-api.sparebank1.no/oauth/token, see example below. The client id and client secret can be found under OAuth Credentials in your registered application in the developer portal.
curl -X POST \
'https://developer-api.sparebank1.no/oauth/token' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&client_id=CLIENT_IDc&client_secret=CLIENT_SECRET'
6. Request an API
Use the OAuth token to access any SpareBank 1 API endpoint your application has access to on behalf of the end-user. Example requesting the account API.
curl -X GET \
'https://developer-api.sparebank1.no/open/personal/banking/accounts/all' \
-H 'Authorization: Bearer BEARER_TOKEN' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/vnd.sparebank1.v1+json'
Production
1. Register your application
To get your application registered for production use you need to be a strategic partner of one of the banks in the SpareBank 1 alliance. When the formal process is in place you will be issued with your applications credentials for production: an appkey, a client id and client secret.
2. Select a bank
SpareBank 1 is an alliance of banks. In order for the end-user to authenticate with any one of these, you need the bank's identifier. Fetch the complete list of banks:
$ curl https://api.sparebank1.no/common/financial-institutions/banks --header "AppKey:d29e819a-6373-4614-a155-9655020cfc7c"
End-user authorizationwhere AppKey is the value issued to your application.The SpareBank 1 API uses the OAuth 2.0 protocol to authorize calls.
3. Authenticate and authorize the end-user
The end-user authenticates using BankID and authorizes your application to access the SpareBank 1 API on its behalf.
Open in a browser: https://api.sparebank1.no/oauth/authorize?finInst=fid-smn&client_id=0f603d09-636f-4b3e-96fd-d56dc7d1a1a3&state=3138229&redirect_uri=https%3A%2F%2Fthisisyou.com&response_type=code
where
- finInst is your bank's identifier
- client_id is the value issued to your application
- state is any client-defined value
- redirect_uri is where the client is redirected after authentication; Must match a pre-configured redirect URI for your application
- response_type must be "code"
After successful authentication and authorization, the browser redirects to your site: https://thisisyou.com?code=zNuDsEr5EE8Tsshdy1Sjr1qv7eU13j&state=3138229
Extract the authentication code from the code parameter.
4. Issue an OAuth token
Pass your application's credentials, along with the end-user's authentication code, to SpareBank 1 to be issued a bearer token. A bearer token enables you to complete actions on behalf of, and with the approval of, the end-user.
Submit a POST request with a x-www-form-urlencoded body to https://api.sparebank1.no/oauth/token.
Sample request body parameters
client_id:0f603d09-636f-4b3e-96fd-d56dc7d1a1a3
client_secret:89d46274-7ce2-4e0b-9048-3eded7d5c115
redirect_uri:http://thisisyou.com
grant_type:authorization_code
code:zNuDsEr5EE8Tsshdy1Sjr1qv7eU13j
state:3138229
Sample response
{
"access_token": "9VKwFeoS8QfeQEeFxD5MiOf6YlFQR0nOpLF1ZUrHRrWqp3rY7G13hy",
"token_type": "Bearer",
"expires_in": 15551999,
"scope": "resource.WRITE resource.READ",
"finInst": "fid-smn",
"state": "3138229"
}
Extract the access_token from the response.
This OAuth token authorizes the end-user's access to API endpoints, and is valid for six months.
5. Invoke an API
The SpareBank 1 APIs are HTTP-based RESTful APIs, using JSON-formatted requests and response bodies.
Use the OAuth token to access any SpareBank 1 API endpoint your application has access to on behalf of the end-user. E.g. the accounts API:
$ curl https://api.sparebank1.no/personal/banking/accounts/all --header "Authorization:Bearer 9VKwFeoS8QfeQEeFxD5MiOf6YlFQR0nOpLF1ZUrHRrWqp3rY7G13hy"
Andre tema