General information

Our API is based on the OAuth2 standard which works with following entities:

  • Access token: This Token is passed in the header of every request in the header key 'Authorization'. It is received after successfull authentication and is valid for 12 hours.
  • Refresh token: This Token is received after successfull authentication (only for Grant 'Authorization Code') and does not expire. It can be used to generate new access tokens. The refresh token can only be used once to fetch a new access / refresh token pair. The newly received refresh tokens are then used for further calls.
  • Client (ID/Secret): An entity that has to register itsself in PostFinance SmartBusiness and provide details about what it wants to access (scopes). After registering a client, an ID-Secret pair is provided that is used for every authentication interaction with the API. Important: Never expose your client secret to the public!
  • Authorization Grant type: There are two different grant types (authorization types) available. Client credentials and Authorization code
  • Scopes: A scope is a defined part of the data/system. For example 'contacts' or 'invoices'. When requiring authentication of users and creating clients, you specify what scopes you will want to access. Once defined you can not access beyond your scope level.

Client credentials Grant OR Authorization Code Grant?

You should choose the grant type 'Client credentials', if you would only like to access your own data of your own account. When creating a client, and choosing this grant type, your credentials will only enable you to access your data.

A typical usecase is if you are a programmer yourself, and would like to write a software that interacts with your own data in PostFinance SmartBusiness.

The Grant type 'Authorization Code' is available for software developers that would like to integrate our API into their software and let other clients access their data, without having to hand over their private application credentials.

A typical usecase of the grant type 'Authorization Code' would be a webshop-softwareprovider that lets their users connect PostFinance SmartBusiness-accounts to automatically create invoices upon incoming orders for them.

Where to create the Client-ID & Secret

You can create as many client ids (every application / usecase should be separated by creating a separate client id) in your account in the main section 'Home' then 'Users->API V2'.

Obtain Access token with Grant type 'Client credentials'

To obtain the access token required for making an API call you need to make following HTTP request

URL: https://api-smartbusiness.postfinance.ch/v2/auth/access-tokens
Method: POST
HTTP-Header: Content-Type: application/json

BODY:
{
    "grant_type":"client_credentials",
    "client_id":"YOUR_CLIENT_ID",
    "client_secret":"YOUR_CLIENT_SECRET",
    "scope":"YOURSCOPES SEPARATED BY SPACE"
}

If successfull, this will return you the following

{
    "token_type":"Bearer",
    "expires_in":43200,
    "access_token":"YOUR_ACCESS_TOKEN"
}

This access token can now be used to make API-Requests, and is passed as header value 'Authorization' (See Introduction)
When the token expires, a new access token should be generated in the same manner.


Obtain Access & Refresh token with Grant type 'Authorization Code'

The process of retreiving the access and refresh token from a user is interactive. The user who wants to provide access to his account, will have to follow through an authorization process that in the end will deliver a refresh and access token to the initiator/software provider/client.

Either open a popup, or redirect the user to the URL with below described GET parameters

https://api-smartbusiness.postfinance.ch/v2/auth/authorize

GET Parameter Value
scope All scopes you require to access, separated by space
response_type Always use 'code'
client_id The client id of the application provider (software developer)
redirect_uri The URL that will receive the authorization code. Has to be identical to the one that was entered when registering the client.
state Randomly generated string that will be returned after the user has authenticated himself. Remember this value and compare it to the incoming value as a security measure.

Example: https://api-smartbusiness.postfinance.ch/v2/auth/authorize?scope=contact&state=RANDOMGENERATEDSTRING&response_type=code&client_id=YOURCLIENTID&redirect_uri=YOURREDIRECTURI

The user will be promted to login with his credentials, and grant access to the specified scopes of the requesting application.

Upon granting access, the browser will make a GET request to the provided redirect_uri passing following GET parameters

GET Parameter Value
code This is your Authorization code to be used further below
state Compare the provided state, with the state value you generated earlier (reject the proces if those values do not match)

At this point you can fetch the Access and Refresh-Token making the following POST-Request:

URL: https://api-smartbusiness.postfinance.ch/v2/auth/access-tokens
Method: POST
HTTP-Header: Content-Type: application/json

BODY:
{
    "grant_type":"authorization_code",
    "client_id":"YOUR_CLIENT_ID",
    "client_secret":"YOUR_CLIENT_SECRET",
    "scope":"YOURSCOPES SEPARATED BY SPACE",
    "redirect_uri":"YOUR_REDIRECT_URI",
    "code":"THE_RECEIVED_AUTHORIZATION_CODE"
}

If the call is successfull, you will receive the following output

{
    "token_type":"Bearer",
    "expires_in":43200,
    "access_token":"ACCESS_TOKEN_OF_USER",
    "refresh_token":"REFRESH_TOKEN_OF_USER"
}

You can now immediately use the access token to make an API-Request.

If you would like to be able to make API requests after the access token has expired, you need to store the refresh token of this user in your database / permanent storage.

To get a new access token (and refresh token) for the user, you can make following POST-Request using the stored Refresh token

URL: https://api-smartbusiness.postfinance.ch/v2/auth/access-tokens
Method: POST
HTTP-Header: Content-Type: application/json

BODY:
{
    "grant_type":"refresh_token",
    "client_id":"YOUR_CLIENT_ID",
    "client_secret":"YOUR_CLIENT_SECRET",
    "scope":"YOURSCOPES SEPARATED BY SPACE",
    "refresh_token":"YOUR_STORED_REFRESH_TOKEN_FROM_USER"
}

This will return you a new access token for the user:

{
    "token_type":"Bearer",
    "expires_in":43200,
    "access_token":"ACCESS_TOKEN_OF_USER",
    "refresh_token":"NEW_REFRESH_TOKEN_OF_USER_THAT_YOU_HAVE_TO_STORE"
}

IMPORTANT: When using the refresh token for fetching new access tokens, the refresh token used is automatically revoked, and you will have to store the new refresh token received for the next time you want to fetch a new access token.