Enterprise Auth

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 acceptable
scope: defined the scope(s) of the requested access token
user_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.

Test the API

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