Migrate legacy token to JWT

In the legacy authentication model, each Client ID (your integration ID) and Tenant ID (your customer's ID) had a single long-lived token. This legacy token did not require frequent renewal, making it easy to use across multiple instances of your integration. However, this approach had security and manageability drawbacks.

With OAuth 2 Authorization Code flow, authentication works differently:

You receive both an access token and a refresh token after authentication.
The access token (used for API requests) is valid for one hour.
The refresh token (used to obtain a new access token) is valid for 45 days but can only be used once.

Managing Token Refresh

To maintain uninterrupted access, your integration must:

Use the access token until it expires (max one hour).
Call the refresh token endpoint before expiration to obtain:
- A new access token
- A new refresh token

Since the refresh token can only be used once, careful management is required. If multiple instances of your integration attempt to refresh the token simultaneously, it could result in token invalidation. To prevent this, consider the following strategies:

Locking Mechanism: Ensure that only one instance initiates the token refresh process at a time. This can be achieved using distributed locks in Redis or a database.
Centralized Token Management: Designate a single component within your integration to handle token renewal and securely distribute the updated access token to other instances.

Handling Expired or Revoked Refresh Tokens

While refresh tokens are typically valid for 45 days, they can become invalid earlier due to:

Revocation (customer manually revokes access).
Expiration (if the integration fails to refresh in time).
Security Policies (e.g., OAuth provider enforces stricter policies).

If this happens, your integration must detect the issue and guide the user through reauthorization.

NOTE: Before you start to migrate, the integration needs to be set to use OAuth 2.0 flow.

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

Headers example

ClientId: 8VurtMGDTeAI
ClientSecret: yFKwme8LEQ
Credentials: OFZ1cnRNR0RUZUFJOnlGS3dtZThMRVE=

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

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

Body example

The body shall be sent by using the "application/x-www-form-urlencoded" format, with a character encoding of UTF-8.

access_token (required) - The legacy token you want to migrate to JWT

access_token={legacy-token}

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

Possible error responses

Status: 401
Message: Invalid authorization

Status: 400
Message: Could not create JWT

Status: 400
Message: Could not create JWT, due to incorrect auth flow type

Status: 403
Message: Not allowed to create JWT for given access-token

Status: 403
Message: Not allowed to create JWT, due to missing license

Status: 404
Message: Access-token not found

FAQ

Can I migrate the same token multiple times?
No, once you exchange your token for a JWT, the old legacy token expires.

Can I migrate from one client ID to another?
No, the migration must use the same client ID.

If we don't support JWT, can I still use the integration after April 30, 2025?
No, if you do not support JWT by April 30, 2025, you will no longer be able to access the Fortnox API.

I don't have access to a developer portal.
Please contact our support team, and they will assist you.

Will my customers be affected?
No, your customers using legacy tokens will not need to re-authenticate.

If I change to oauth2 in the developer portal, will my old legacy tokens stop working immediately?
No, you will still be able to use your legacy tokens up until April 30th.

Will my new access token have the same scopes that I have added in the developer portal?
No, your scopes will be the same as they were for the legacy token, if you wish to update the scopes the customer will have to re-authenticate

Documentation

See our comprehensive documentation regarding the Fortnox API.

Join us

Approximately half a million customers are waiting for your integration at our Integrations page.