Join us at Fortnox App Market today!

Authorization

Developers Integration Dictionary

During the process of creating your integration you will bump into these words and functions.

Authorizing your integration

The authorization of access to a customer’s account is made using the OAuth2 Authorization Code Flow. In essence, this means that a user grants your application access to their account. The user must approve the access and scope of access to their account during the activation process.

Below is an overview of the Authorization Code Flow. The flow starts at your application’s landing page. Authentication of the user is handled through the standard Fortnox login process as part of the flow.

  1. The App Backend attempts to access a resource that requires authorization that it does not have. It redirects the user to the authorization server for authentication.
  2. The Authorization Server authenticates the user by asking for their login credentials. The server determines if the user should be granted or denied their request.
  3. If the User is determined to be authentic, an Authorization-Code is issued and returned to the App Frontend. This code is used to retrieve an Access-Token from the Authorization Server.
  4. The retrieved Authorization-Code is sent to the App Backend.
  5. The App Backend makes a POST request to the Authorization Server, containing its Client-ID, Client-Secret, and Authorization-Code.
  6. The Authorization Server verifies the key, secret and code, and issues an Access-Token and Refresh-Token.
  7. The App Backend receives and processes the Access-Token. The Access-Token is then kept in the App Backend, which can request resources on behalf of the App Frontend without exposing the token itself.
Client-Id The integrators key to exchange an Authorization-Code for an Access-Token (unique for the application and connected to the Client-Id)
Client-Secret Generated when the customer authenticates and approves the connection between their account and your application
Authorization-Code Generated when the customer authenticates and approves the connection between their account and your application
Access-Token Token with limited lifetime used by your application when making API requests on behalf of a user.
Refresh-Token
Long-lived token used to generate a new Access-Token once the old one has expired.

The Client-Id, Client-Secret and Authorization-Code are only used during initial authorization of the connection between a customer’s account and your application.

The Access-Token is used when making regular API calls from your application.

The Refresh-Token is used when an Access-Token has expired. The Refresh-Token should be kept secret.

Request examples

Get Authorization-Code

GET https://apps.fortnox.se/oauth-v1/auth?client_id={Client-ID}&redirect_uri=https%3A%2F%2Fmysite.org%2Factivation&scope=companyinformation&state=somestate123&access_type=offline&response_type=code

Parameters

client_id (required) The client_id is the public identifier for the app.
respone_type (required) The response_type should be set to code, indicating that the application expects to receive an authorization code if successful.
state (required) The state parameter is used by the application to store request-specific data and/or prevent CSRF attacks. The authorization server will return the unmodified state value back to the application.
scope (required) The request should have one or more scope values indicating access requested by the application. The authorization server will display the requested scopes to the user. The scope parameter is a list of URL-encoded space-delimited, case-sensitive strings.A full list of scopes can be found here. Example: scope=article%20companyinformation
redirect_uri (optional) URL-encoded URI that must match the Redirect URI for the app set in the Developer Portal. If omitted, it will default to the registered Redirect URI.
access_type (optional) Indicates whether your app can refresh access tokens when the user is not present at the browser. Should be set to offline.

Users will be redirected to a login screen where authentication is performed using regular Fortnox user credentials. Upon successful authentication, the server responds with a redirect containing the Authorization-Code.

Response redirect

https://mysite.org/activation?code={Authorization-Code}&state=somestate123

Exchange Authorization-Code for tokens

POST https://apps.fortnox.se/oauth-v1/token

Headers

CREDENTIALS is the Base64 encoding of ClientId and Client-Secret, separated with a colon.

Example:

ClientId: 8VurtMGDTeAI
ClientSecret: yFKwme8LEQ
Credentials: OFZ1cnRNR0RUZUFJOnlGS3dtZThMRVE=

Content-type: application/x-www-form-urlencoded
Authorization: Basic {Credentials}

Body

grant_type=authorization_code&code={Authorization-Code}&redirect_uri=https://mysite.org/activation

Response

{
  "access_token": "xyz...",
  "refresh_token": "a7302e6b-b1cb-4508-b884-cf9abd9a51de",
  "scope": "companyinformation",
  "expires_in": 600,
  "token_type": "Bearer"
}

Refresh Access-Token

POST https://apps.fortnox.se/oauth-v1/token

Headers

Content-type: application/x-www-form-urlencoded
Authorization: Basic {Credentials}

Body

grant_type=refresh_token&refresh_token={Refresh-Token}

Response

{
  "access_token": "xyz...",
  "refresh_token": "a7302e6b-b1cb-4508-b884-cf9abd9a51de",
  "scope": "companyinformation",
  "expires_in": 600,
  "token_type": "Bearer"

}

API call

GET https://api.fortnox.se/3/companyinformation

Headers

Authorization: Bearer {Access-Token}