Getting started
This section describes the practical steps to get up and running in the SpareBank 1 sandbox environment.
Introduction
All of the API's within the portal will respond with static data from a closed sandbox environment. The API's deployed in the sandbox is the same as in production. 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.
Registration
- The URL to the developer portal is https://developer.sparebank1.no/.
- Press the "Sign In" button which will take you to the login page.
- As a new user, press "Sign up" under the "Login Name" field.
- Fill inn the fields:
- Full 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 accessed from the bottom of the screen.
- If you agree to the terms, tick off the "I agree" selection, and press the Sign up button.
- 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 log into the API portal.
Login to the developer portal
Sign in with your login name (email) and password chosen during the registration.
Development
Create application
1. Choose "Applications" from the top menu and press the button "Create application".
2. Fill in the mandatory fields (and any optional fields if desired).
3. 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.
4. Save your application
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.
1. 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.
Basic testing of an API from the Developer portal.
1. Click "APIs" from the top menu.
2. Click on the API you want to test.
3. Choose the OAuth client from the application you created (see drop-down list).
4. 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.
5. Click the URI you want to test and fill in the parameters needed (if any).
6. Scroll down and press "Try it out" to send the request.
7. You will then see the response, body and header.
Invoke an API outside the developer portal
The SpareBank 1 APIs are HTTP-based RESTful APIs, using JSON-formatted requests and response bodies.
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'
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
This section describes the practical steps to get up and running in the SpareBank 1 production environment for partners with an agreement to use API’s.
Register your application
Registered applications are issued application credentials: An AppKey, a client ID, and a client secret.
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.
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.
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.
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.
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"
