Enterprise Authentication
Access to the Enterprise API requires use of the Enterprise Authentication API. You can test the available features, data and possibilities in sandbox environment freely, but partnerships and access to production environment will be evaluated on an case by case basis.
The authentication is based on a client ID and a client secret that should be used to obtain access tokens to access the Enterprise API.
There are two kinds of access tokens for this API:
- Client credentials: the client credentials (i.e., ID and client secret) are used directly as an authorization grant to obtain an access token
- End-user credentials: the client credentials are used along with end-user provided authorization (through BankID) to obtain an access token that allows access to the secured information of the current user (such as the user's loans)
Bearer token authentication
A personal sandbox account can be used to authenticate, and you can create one here if you haven't done so yet, for free.
The authorization key you receive when registering is a bearer token that should be sent on the Authorization
header
of every request during the authentication or authorization flows. It is the most simple way to test secured calls.
Note that this method of authentication is very similar to what would be required in a production environment when accessing the Enterprise API, except that the bearer token would be the one assigned to the TPP.
API usage
For all the calls to the Enterprise Authentication API, remember that you will be required to specify the Authorization
header, providing your Sandbox bearer token.
Client Credentials
Most of the Enterprise API operations require an access token obtained through client credentials, including doing a loan pre-approval or a loan application.
For this simple flow, you only have to request a new access token using your client ID and client secret. In the sandbox that role is taken by your personal bearer token, like so:
curl -X POST \
"https://developer.sbab.se/sandbox/api/auth/1.0/token" \
-H "Accept: application/json" \
-H "Authorization: Bearer 12345678-90ab-cdef-1234-567890abcdef" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d grant_type=client_credentials
The response would look like the following:
{
"access_token": "3b536ddc-986a-477c-8cf5-ce1e867845a4",
"expires_in": 300,
"auth_method": "authorize",
"token_type": "bearer"
}
Now you can use the given access_token
as a bearer token in most Enterprise API requests for the next 5 minutes
(300 seconds).
End-user Credentials
The access tokens obtained by this flow are currently only used for accessing the end-user's loans.
You start your authentication by calling the Enterprise authorize
endpoint:
curl -X GET -G \
"https://developer.sbab.se/sandbox/api/auth/1.0/authorize" \
-H "Accept: application/json" \
-H "Authorization: Bearer 12345678-90ab-cdef-1234-567890abcdef" \
-d client_id=my_client_id \
-d response_type=pending_code \
-d scope=account.read,account.write,loan.read \
-d user_id=191212121212
Observe a few important parameters:
client_id
: a client ID provided to you by SBAB; in the sandbox any value is acceptablescope
: defined the scope(s) of the requested access tokenuser_id
: the Swedish personal number of the end user; in the sandbox any valid value is acceptable (meaning it has correct format and valid checksum digit)
The result to this call is something like this:
{
"pending_authorization_code": "5db82ad9-3dfa-40fb-b7df-4b2728155829",
"autostart_token": "ee083cfd-e847-4c6f-a1a1-09c355f1f3c9"
}
The autostart_token
would need to be used to initiate BankID, such as by redirecting the user to a URL like this:
bankid://?autostarttoken=ee083cfd-e847-4c6f-a1a1-09c355f1f3c9&redirect=null
Yet this is not needed on the sandbox, as BankID was not actually invoked and the authorization is assumed to be successful.
The next step would be exchanging the pending authentication code for an access token, like so:
curl -X POST \
"https://developer.sbab.se/sandbox/api/auth/1.0/token" \
-H "Accept: application/json" \
-H "Authorization: Bearer 12345678-90ab-cdef-1234-567890abcdef" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d grant_type=pending_authorization_code \
-d pending_code=5db82ad9-3dfa-40fb-b7df-4b2728155829
Again, observe that pending_code
is the value received in the previous call. Other than a failure caused by many of
the various situations exposed above, the response should look like the following:
{
"access_token": "e3f1c3c8-0374-41aa-9295-08483b997b76",
"expires_in": 300,
"auth_method": "authorize",
"token_type": "bearer"
}
Now you can use the given access_token
as a bearer token in any requests to the Enterprise API for the next 5 minutes
(300 seconds).
Try it yourself
We recommend that you test the steps above in our sandbox environment, if you haven't done so yet.
Production Gateway URL
When you move into production use of our APIs, remember to change the domain from the sandbox one to the production one:
https://api.sbab.se