Föreningssupport REST API

Föreningssupport API 2.0 is a new version of our API and will replace all previous versions. The API is designed using the REST standard, supporting POST, GET, PUT and DELETE requests. Also available in Swagger UI for online documentation at; https://api.foreningssupport.se

Applications can connect to this API using OAuth2 Authentication and access token.

How do I get access?

Please contact us at support@foreningssupport.se and tell us something about your integration. We will create a client and provide you with clientId and clientSecret. Each client must be assigned one or more scopes.

Current available scopes are; fs.api.members, fs.api.invoices, fs.api.gifts.

Each scope lets you access data from our endpoints. If an endpoint requires a scope your client is not assigned, you will get a 403 Forbidden result.

When you have your clientId and clientSecret, you can use these together with an API key in order to obtain access tokens for accessing your customer data. The API key can be created by the account owner or by our support staff. Another option is to develop a public integration with full OAuth Flow. More details will follow regarding these two options.


Environments:

FS 2.0 API Base URL

https://api.foreningssupport.se

FS IdentityServer Authorization

https://identity.foreningssupport.se/connect/authorize

FS IdentityServer Token

https://identity.foreningssupport.se/connect/token


Authentication

In order to get data from our API, you must be authorized with an access token on every request.

There are two options available:


  1. Private integrations. With an API key you can obtain an access token which is tied to your customer account directly. This is the way to go for playing around and fetching data from our API with full access to the data in your customer account.


  2. Public integration with full OAuth Flow which allows users and members to sign in and use your integration. Every access token is tied to the end user after signing in. Use this approach if you want to create your own application and fetch data on behalf of the member or user, and also their permissions.

Private integrations

This guide will show you how to get an access token, created with API-key using the OAuth Flow “Password Grant” (https://tools.ietf.org/html/rfc6749#section-1.3.3).

Example request:

curl -X POST \ 
-H "Content-Type: application/x-www-form-urlencoded" \ 
-d "client_id: $CLIENT_ID" \ 
-d "client_secret: $CLIENT_SECRET" \ 
-d "grant_type: password" \ 
-d "username: $API_KEY" \ 
-d "password: apiKey" \ 

'https://identity.foreningssupport.se/connect/token'

Response:

{ 
"access_token": "{ACCESS_TOKEN}", 
"expires_in": 86400, 
"token_type": "Bearer", 
"refresh_token": "{REFRESH_TOKEN}", 
"scope": "fs.api fs.api.gifts fs.api.invoices fs.api.members offline_access" 
}

Important! Consider saving this access token in your client (back-end cache or database storage). Each access token has an expire date, please honor the value in "expires_in" and don’t request tokens on each request to prevent being blocked by our systems.


Public integration with full OAuth Flow

This guide will show you how to get an access token using the full OAuth Flow "Code Flow Grant" (https://tools.ietf.org/html/rfc6749#section-4.1 ).

You will be required to provide us information about:

  • Name of your integration
  • Redirect-URI where user is returned to for exchanging the code to an access token

To start the authorization flow, you need to redirect the user to the following URL:

https://identity.foreningssupport.se/connect/authorize?client_id={CLIENT_ID}&response_type=code&redirect_uri={REDIRECT_URI}&state={STATE}&scope= offline_access openid profile fs.api fs.api.members

This URL allows the user to authenticate and lets them authorize access to their account depending on your OAuth2 Application settings and their choice.

After a successful authorization, the user will be redirected back to the Redirect URL for your OAuth2 application. These parameters will be attached:

  • Code – an authorization code that you will have to exchange for a set of Refresh and Access Tokens. You will be able to use this Access Token to access the user’s account on their behalf.
  • State – (optional) contains the original value for the state parameter that was passed at the beginning of the authorization.
  • Scope – contains a list of space-separated strings describing the granted access scope.

Once you have the Authorization Code, you can exchange it for a set of Access and Refresh Tokens:

curl -X POST \ 
-d "code=$AUTHORIZATION_CODE" \ 
-d "client_id=$CLIENT_ID" \ 
-d "client_secret=$CLIENT_SECRET" \ 
-d "grant_type=authorization_code" \ 
-d "redirect_uri=$REDIRECT_URI" \ 
'https://identity.foreningssupport.se/connect/token'

Response:

{ 
"access_token": "{ACCESS_TOKEN}", 
"expires_in": 3600, 
"token_type": "Bearer", 
"refresh_token": "{REFRESH_TOKEN}", 
"scope": "fs.api fs.api.gifts fs.api.invoices fs.api.members offline_access" 
}

When your Access Token is about to expire, you can use the Refresh Token to get a new Access Token:

curl -X POST \ 
-H "Accept: application/json" \
-d "refresh_token= $REFRESH_TOKEN" \ 
-d "client_id=$CLIENT_ID" \ 
-d "client_secret=$CLIENT_SECRET" \ 
-d "grant_type=refresh_token" \ 
'https://identity.foreningssupport.se/connect/token'

Response:

{ 
"access_token": "{NEW_ACCESS_TOKEN}", 
"refresh_token": "{REFRESH_TOKEN}", 
"token_type": "Bearer", 
"expires_in": 3600 
}

Using the Access Token

The access token must be provided in all requests. It should be provided as a bearer type in the header.

Example request:

curl -X GET 
-H "Authorization: Bearer eyJhbGciOiJSUzI1N………" \ 'https://api.foreningssupport.se/api/v1/user/me'